%&LaTeX (tells OzTeX to use LaTeX.fmt)
% Source file for the "OzTeX User Guide".
% Non-LaTeX cross references are flagged by "XREF".
% Unfinished or uncertain portions are flagged by "!!!" or "???".
\documentclass[11pt]{article}
\usepackage{hyperref}              % add HyperTeX links
\oddsidemargin=0in
\evensidemargin=0in
\textwidth=6.3in
\topmargin=-0.4in
\headheight=0.2in
\headsep=0.5in
\textheight=9.4in                  % better for US Letter paper
\input OzTeX                       % OzTeX logo
\def\OzMF{OzMF}
\def\OzMP{OzMP}
\let\pOzTeX=\OzTeX
\let\pOzMF=\OzMF
\let\pOzMP=\OzMP
\def\OzTeX{\protect\pOzTeX}        % protect "OzTeX" in page headings
\def\OzMF{\protect\pOzMF}          % protect "OzMF" in page headings
\def\OzMP{\protect\pOzMP}          % protect "OzMP" in page headings
\font\logo=logo10 scaled\magstephalf
\def\readme{{\tt Read-Me}}
\def\ozprefs{{\tt OzTeX~Prefs}}
\def\texbook{{\sl The \TeX book\/}}
\def\initex{{\tt INITEX\null}}
\def\inimf{{\tt INIMF\null}}
\def\inimp{{\tt INIMP\null}}
\def\configs{{\tt Configs}}
\def\oztext{{\tt Oz.text}}
\def\pool{{\tt TeX.pool}}
\def\textpro{{\tt TEXTtoPS.pro}}
\def\pkfiles{{\tt PK-files}}
\def\psfiles{{\tt PS-files}}
\def\encfiles{{\tt Encodings}}
\def\stdenc{{\tt Mac.enc}}
\def\vffiles{{\tt VF-files}}
\def\texfonts{{\tt TeX-fonts}}
\def\texinputs{{\tt TeX-inputs}}
\def\texformats{{\tt TeX-formats}}
\def\helpfiles{{\tt Help-files}}
\def\texdocs{{\tt TeX-docs}}
\def\latexdocs{{\tt LaTeX-docs}}
\def\ttedit{{\tt AlphaLite}}
\def\dvf{{\tt DVIPS}}
\def\dvips{{\tt dvips}}
\def\mff{{\tt Metafont}}
\def\mpf{{\tt MetaPost}}
\def\mf{{\logo METAFONT\null}}
\def\missfont{{\tt missfont.make}}
\raggedbottom
\begin{document}
\null
\vfil
\centerline{\hbox to 30bp{\special{pntg=ozicon}\hfil}}
\bigskip
\begin{center}
\Huge\bf
\OzTeX\ User Guide\\ [3mm]
\normalsize\bf
Version 3.0, February 1997\\ [3mm]
Andrew Trevorrow\\
akt@kagi.com\\
http://www.kagi.com/authors/akt/
\end{center}
\bigskip
\bigskip
\noindent
\OzTeX\ is a Macintosh implementation of Donald Knuth's \TeX\ typesetting
system.  This document assumes you know how to use a Macintosh.
It also assumes you know how to create a \TeX\ (or \LaTeX) input file.
If you have access to a PostScript printer then an understanding of
PostScript would be useful, but it is not essential.
\OzTeX\ aims to provide a standard \TeX\ environment for the Macintosh
that is easy to extend or customize to suit your particular needs.
If you have used \TeX\ on some other computer then the way
\OzTeX\ works shouldn't be too surprising.
\OzTeX\ is shareware, so you are welcome to try it out before paying
the registration fee (see the ``Shareware Fee'' item in \OzTeX's Help menu
for details about how to pay).
Comments, bug reports and suggestions are all welcome, but please note
that I only reply to e-mail queries from registered individuals.
\vfil
\thispagestyle{empty}
\pagenumbering{roman}
\newpage
\pagestyle{headings}
\tableofcontents
\newpage
\pagenumbering{arabic}
\section{Introduction}
Assuming you correctly carried out the installation instructions in the
\readme\ file supplied with \OzTeX, you should have a folder that looks
something like this:
\vbox to 2.8in{\label{folders}\vfil
\noindent\hskip 1.1in\special{pntg=folders scale=0.72}}
\bigskip
\noindent
Here's a brief description of what's inside all those folders:
\begin{itemize}
\item
The \texinputs\ folder contains a large number of \TeX\ input files
stored in various subfolders.  \TeX\ looks in these subfolders
if it can't find a given file in your current folder.
The supplied subfolders contain the files needed to use
Plain \TeX, \LaTeX\ and REV\TeX\null.
If you have your own library of macro files then the
best place for them is in a new subfolder in \texinputs.
\item
The \texformats\ folder contains the format files read by \TeX\ and
the \pool\ file read by \initex.
The three most popular formats are supplied:
{\tt Plain.fmt}, {\tt LaTeX.fmt} and {\tt AMSTeX.fmt}.
Section~\ref{fmt-sec} describes how to create format files.
\item
The \texfonts\ folder contains many \TeX\ font metric files
stored in various subfolders.
These TFM files are required by \TeX\ to carry out typesetting;
see section~\ref{tfm-sec}.
\item
The \vffiles\ folder contains virtual font files;
see section~\ref{vf-sec}.
\item
The \psfiles\ folder contains various PostScript files.
It also contains encoding files in the \encfiles\ subfolder;
see section~\ref{enc-sec}.
\item
The \pkfiles\ folder contains PK font files stored in various subfolders.
The name of each subfolder indicates the ``size'' of the PK files kept
within it; see section~\ref{pk-sec} for how this size is calculated
and for more information about PK files.
\OzTeX\ is distributed with a fairly small set of PK files
(sufficient to print out the documentation on most printers).
New PK files at any desired size can be built on demand;
see section~\ref{mf-sec}.
\item
The \configs\ folder contains \OzTeX's configuration files.
The most important of these is the {\tt Default} file loaded by
\OzTeX\ when it starts up.
See section~\ref{config-sec} for a detailed discussion of
configuration files, including the required syntax.
\item
The \mff\ folder contains files needed by \OzMF,
a Mac implementation of Donald Knuth's \mf\ program
and other font related tools.
The {\tt Default} config file loaded by \OzMF\ is in the
\configs\ subfolder in \mff.
See section~\ref{mf-sec} for more information about \OzMF.
\item
The \mpf\ folder contains files needed by \OzMP,
a Mac implementation of John Hobby's MetaPost program.
The {\tt Default} config file loaded by \OzMP\ is in the
\configs\ subfolder in \mpf.
See section~\ref{mp-sec} for more information about \OzMP.
\item
The \dvf\ folder contains files needed by \dvips,
Tom Rokicki's popular DVI-to-PostScript translator.
The \OzTeX\ application contains an enhanced version of \dvips.
See section~\ref{dvips-sec} for more information.
\item
The \texdocs\ folder contains examples of Plain \TeX\ files,
including \verb|nasty.tex| which is used in the guided tour of \OzTeX.
It also contains \verb|gentle.tex|, the source file for Michael Doob's
{\sl A Gentle Introduction to \TeX}\null.
\TeX\ beginners should find this a useful companion to \texbook\ by Donald Knuth.
\item
The \latexdocs\ folder contains {\tt ozuser.tex}, the source file for this
user guide, plus {\tt hyper.tex} which shows how to use the {\tt hyperref}
and {\tt color} packages.
Also provided in \latexdocs\ is the \verb|LaTeX Short Course| subfolder
generously donated by George Gr\"atzer; it contains the source files for
Part~I of his book
{\sl Math into \LaTeX\ --- An Introduction to \LaTeX\ and AMS-\LaTeX}\null.
\item
The \helpfiles\ folder contains a number of text files used by \OzTeX\null.
The information in these files can be displayed by selecting their names
from \OzTeX's Help menu.
(Note that the help files for \OzMF\ and \OzMP\ are stored in the
{\tt Help} subfolders in \mff\ and \mpf\ respectively.)
\item
The {\tt AMS} folder contains all the input files for AMS-\TeX\ and
AMS-\LaTeX\null.  It also contains TFM files and \mf\ source files for
the AMS fonts.
\item
The {\tt AlphaLite} folder contains Pete Keleher's AlphaLite application
for editing \TeX/\LaTeX\ input files.
Note that AlphaLite is shareware and comes with its own Register application.
If you prefer to use a different editor then throw away the {\tt AlphaLite} folder.
\item
The {\tt BibTeX} folder contains Vince Darley's port of Bib\TeX\ which
can be used in conjunction with \LaTeX\ to generate a bibliography from
information stored in a bibliographic database.
\item
The {\tt MakeIndex} folder contains Rick Zaccone's port of MakeIndex
for creating a sorted index.
\item
The {\tt Excalibur} folder contains Excalibur, a spelling checker
written by Rick Zaccone and Robert Gottshall.
Excalibur was designed to handle \LaTeX\ documents, but also works
quite well with Plain \TeX\ files.
\item
The {\tt Register} folder contains the Register application for paying
\OzTeX's shareware fee.  Some brief notes on how to use Register are
also included.
\end{itemize}
The \OzTeX\ folder can be called anything you like, and can be moved anywhere
on your disk.  However, if you decide to rename some of the above folders or
applications then you'll probably need to make corresponding changes to the
various {\tt Default} configuration files loaded by \OzTeX/\OzMF/\OzMP\null.
The paths to these {\tt Default} files are stored as resource strings in the
preferences file for each application, so you'll also need to use ResEdit
if you want to change the names of the \configs, \mff\ or \mpf\ folders.
If you are new to \OzTeX\ then my advice is to stick to the given
folder names!
\newpage
\section{A guided tour of \OzTeX}
The aim of this section is to get you acquainted with \OzTeX's major features.
\subsection{Starting \OzTeX}
Assuming you've installed everything, double-click on the
\OzTeX\ application file to get the program started.
After a brief pause you should see a window with the title ``\OzTeX''
and a couple of messages showing the current version of \OzTeX\ and
the path name of the {\tt Default} configuration file just loaded.
The {\tt Default} file contains references to an encoding file
called \verb|Mac8r.enc|, so it will also be loaded.
If you made a mistake during installation
then you might get one or more error messages.
The messages should give you some idea of how to fix the problem.
If you need to edit the {\tt Default} file, read section~\ref{config-sec}
for a detailed discussion of configuration files.
The \OzTeX\ window is always present; note that it has no close box
in the top left corner.
This window provides a terminal-like interface for \OzTeX\null.
Text in the window can be copied to the Clipboard or saved to a file.
You can also start up \OzTeX\ by double-clicking on \verb|foo.dvi|.
The advantage of this method is that if \verb|foo.tex| exists then
that file name will appear in the \TeX\ menu, ready for typesetting.
Note that under System~7 or later you can drop \verb|foo.tex| onto
the \OzTeX\ icon and \OzTeX\ will immediately typeset the file.
The production of a \TeX\ document typically involves a number of iterations
through the following cycle: edit, typeset, preview and print.
(People concerned about our dwindling forests will hopefully preview
many more times than they print.)
Let's go through this cycle step by step.
\subsection{Choosing an editor}
\OzTeX\ does not have an integrated text editor, but if you are using
System~7 or later you won't find this too much of a problem.
After installing \OzTeX\ and starting it up for the very first time,
select ``Choose Editor'' from the Edit menu and use the
open-file dialog to locate and select the application you'll be using
to edit your \TeX/\LaTeX\ input files.
If the chosen application supports Apple events then \OzTeX\ remembers
its name and location for use in all future \OzTeX\ sessions (or until
you choose another editor).
Having chosen an editor, \OzTeX\ will use it as the target of an
``open file'' event sent when you select ``Edit foo.tex'' from the Edit menu.
This item always shows the name of the most recently typeset file.
See section~\ref{edit-menu} for more details about the items in the Edit menu.
\subsection{Editing a \TeX\ input file}
A \TeX\ input file is a standard Macintosh text file.
We won't create an input file from scratch, instead we'll use one
of the sample files provided in the \texdocs\ folder.
There is nothing special about this folder, or \latexdocs.
I simply like to keep my \TeX\ and \LaTeX\ input files in separate folders.
You can keep your input files anywhere you like.
The file we'll use is called \verb|nasty.tex|.
As the name suggests, it is not a typical \TeX\ input file,
but it does illustrate most of the things you'll encounter when using
\OzTeX\ in the future.
Switch to your text editor and open \verb|nasty.tex| from the \texdocs\ folder.
The only change we'll make to \verb|nasty.tex| is to add a deliberate error:
insert the illegal command \verb|\xxx| at the start of the file.
Save this change before switching back to \OzTeX.
\subsection{Running \TeX}
Let's now typeset \verb|nasty.tex|.
Before starting \TeX\ we need to make sure that the correct format will be used.
All the available formats appear at the end of the \TeX\ menu.
Check this menu and make sure the Plain format is ticked;
this is the format required by \verb|nasty.tex|.
(This check is not actually needed because the first line of \verb|nasty.tex|
contains ``\verb|%&Plain|'' which forces \OzTeX\ to use the Plain format.)
Choose ``\TeX\,\ldots'' from the \TeX\ menu and open \verb|nasty.tex|.
The \OzTeX\ window will be cleared, \TeX\ will start up,
load the Plain format, and begin reading the given input file.
When it sees the unknown command, \TeX\ will display a suitable error message,
beep, and wait for you to type something.
Note that a solid block cursor sits next to \TeX's ``\verb|?|'' prompt.
This block cursor always appears when \TeX\ is waiting for you to type something.
The \OzTeX\ window should contain the following:
\bigskip
\indent\verb|This is TeX, Version 3.14159 (no format preloaded)|\\
\indent\verb|**&Plain nasty.tex|\\
\indent\verb|(nasty.tex|\\
\indent\verb|! Undefined control sequence.|\\
\indent\verb|l.5 \xxx|\\
\indent\\
\indent\verb|? |{\tt\vrule width .4em height .7em depth .15em}
\bigskip
\noindent
Chapter 6 in \texbook\ explains what you can do in such a situation.
(Section~\ref{edit-menu} describes how you can type ``\verb|e|'' to tell
\OzTeX\ to switch to your editor and open the file containing the error,
possibly with the error line selected.)
In this case we can simply ignore the error and continue
by hitting the Return key.
Although \verb|nasty.tex| is not very nice, you shouldn't see any more
\TeX\ errors.  A 19-page DVI file called \verb|nasty.dvi| should be created.
Have a look at the second item in both the File and View menus.
Whenever a new DVI file is created, its name will automatically appear in
these items so you can quickly print or view the DVI file
without going through the open-file dialog.
The second item in the \TeX\ menu has also been updated with the name
of the most recent input file (\verb|nasty.tex| in this case), so you can
easily typeset the same file again by pressing Command-T\null.
The file name also appears in the bottom item of the Edit menu   % XREF
so you can quickly switch back to your editor by pressing Command-E\null.
\OzTeX\ supports background typesetting.  At any time while \TeX\ is running you
can switch to another application and \TeX\ will continue to run in the background.
Whenever \OzTeX\ finishes a lengthy task in the background (like typesetting
or printing), or if some sort of user interaction is required (say a \TeX\ error
occurs), then under System~6 or later you will be notified by a flashing
\OzTeX\ icon in the menu bar.  A diamond mark will also appear next to
\OzTeX\ in the list of current applications.
At the end of every \TeX\ run, \OzTeX\ displays the time taken and the
amount of memory allocated by \TeX\ for its large arrays.
The total number of bytes depends on the current \TeX\ parameters.
The values in the {\tt Default} config file are suitable for small to
medium-size documents.  For some documents you might need to increase
one or more \TeX\ parameters; you'll know this is necessary if \TeX\ quits
with a ``capacity exceeded'' error; see section~\ref{capacity}.
For very large documents, like a book or thesis, you will probably need to
increase most of the parameters and create big formats; see section~\ref{big-fmt}.
\subsection{Viewing a DVI file}
The next step is to preview the DVI file and check for problems that \TeX\ might
have missed, like missing fonts, bad page breaks, spelling mistakes, etc.
Let's have a look at \verb|nasty.dvi| by choosing the second item in
the View menu.
\OzTeX\ creates a new window, called the ``view'' window, and sets its
title to the selected DVI file.  A dialog box has also appeared:
\vbox to 1.8in{\label{viewdlg}\vfil
\noindent\hskip 1.0in\special{pntg=viewdlg scale=0.72}}
\bigskip
\noindent
The scroll bar allows you to select any page in the DVI file.
There are also two edit boxes in which you can type a DVI page number
or \TeX\ page number.
(The dialog box also allows you to change some other options, but
we'll ignore them at this stage; see the description of ``View DVI\,\ldots''
in section~\ref{view-menu} for details.)
Play around with the scroll bar if you like but make sure
the 2nd DVI page is selected before proceeding.
To view this page simply click on the View button or hit the Return key.
The 2nd page in \verb|nasty.dvi| contains a single rule with some text below it. % XREF
Dotted lines representing the paper edges should also be visible.
Now is a good time to adjust the size and location of the \OzTeX\ and view
windows to suit your screen.  When you quit, \OzTeX\ will remember the current
window settings and use them the next time it starts up.
\subsubsection{Setting the default view}
\label{def-view}
\OzTeX\ displays the top left corner of the paper at a scale approximating
the document's actual size (see below for more about scaling).   % XREF
This is the initial default view, but it might not suit the size
or dimensions of your particular monitor.  To change the default view,
you just set up the desired scale and/or location using the various
commands described below   % XREF
and then select ``Save as Default View'' from the View menu.
\OzTeX\ remembers your new default view until you decide to change it.
To restore the initial default view, simply select ``Actual Size''
from the View menu, move the scroll bar thumb boxes up and to the left
as far as possible, then select ``Save as Default View''.
\subsubsection{Paper coordinates}
\label{paper-coords}
An understanding of the coordinate system used by \OzTeX\ to view
(and print) a DVI page would be useful.
\OzTeX's internal units are called ``paper pixels''.
The resolution parameters in a configuration file define the
number of paper pixels per inch;
the \verb|viewing_resolution| is only used when viewing a DVI file
and the \verb|printing_resolution| is only used when printing
a DVI file on a non-PostScript printer
(for a PostScript printer, \dvips\ uses the resolution specified in
{\tt config.ps}).
\OzTeX\ uses a coordinate scheme in which the paper pixel at (0,0) is
exactly one inch in from the top and left edges of the paper.
This position is referred to as the ``\TeX\ origin'' because it is also
the origin of the coordinate system used in DVI files.
Every character, rule or \verb|\special| has a specific location
defined by a pair of paper pixels ($h$,$v$).
Vertical coordinates increase down the paper and
horizontal coordinates increase to the right.
If the view window is frontmost then the cursor is changed to a cross
whenever it moves over the contents region.  The current position of the
cross is shown (in paper coordinates) in a box at the lower left corner
of the view window.  You can click in this box to change units
(set the units to {\tt px} to see paper pixel values).
\subsubsection{Zooming in and out}
A ``scale factor'' is used to display a DVI page at a particular size.
It defines the number of paper pixels in each Macintosh screen pixel
(both horizontally and vertically) and always has an integer value
greater than or equal to~1.
Certain View menu items change the current scale factor:
\begin{itemize}
\itemsep=0pt
\item
``Full View'' sets the scale factor to its maximum value and displays
the entire page and paper edges in the middle of the view window.
\item
``Actual Size'' sets the scale factor so that the new view will show the
page at roughly the right size
(it's only approximate because the scale factor is an integer value).
\item
``Zoom In'' halves the current scale factor.
\item
``Zoom Out'' doubles the current scale factor.
\end{itemize}
You can also change the scale factor by clicking in the view window
in a variety of ways:
\begin{itemize}
\itemsep=0pt
\item
A simple click will temporarily magnify the area under the cursor until
the mouse button is released.  The scale factor in the magnified area is~1.
The magnified area can be moved around and if the mouse moves outside the
viewing area then scrolling will occur.
\item
Command-click will zoom in by decrementing the scale factor.
\item
Option-click will zoom out by incrementing the scale factor.
\item
Shift-click will zoom out by doubling the scale factor.
\item
Option-Command-click will zoom in by halving the scale factor.  However,
if the mouse is dragged then \OzTeX\ will zoom in to the selected rectangle
(to cancel this operation, make the rectangle very thin).
\item
A beep occurs if you can't zoom in or out any further.
\end{itemize}
When you zoom in or out by clicking, \OzTeX\ will try to make the
point you clicked the middle of the new view.
However, when you choose a menu item, \OzTeX\ tries to keep the top left
page location fixed.
In both cases it is possible that the view may unexpectedly shift so that it
remains within the scrolling limits set by \OzTeX\null.
Experiment with the various ways of zooming to see which methods you prefer.
The most precise display occurs when the scale factor is~1
because each screen pixel corresponds to exactly one paper pixel.
\OzTeX\ doesn't allow you to zoom in any further than this.
\subsubsection{Scrolling around}
The view window has scroll bars that allow you to
move over the page in the standard Macintosh manner.
Note that the arrow keys can be used instead of clicking in the scroll arrows.
\OzTeX\ won't let you get too far away from the page/paper boundaries.
If you do manage to get lost just choose ``Full View''.
\subsubsection{Checking for errors}
It is a good idea to select the ``Page Info'' item at least once while
viewing a DVI file.  This item displays its results in the \OzTeX\ window.
The display includes a list of all the fonts used in the DVI file and
clearly indicates any that are missing.
(If virtual fonts are used then ``Page Info'' won't necessarily detect
all missing PK fonts.  A missing PK font referenced in a virtual font
will only be detected if a character requiring that PK font is used
somewhere on the current page.)
\OzTeX\ also lists any \verb|\special| commands on the current page,
showing their locations and arguments.
\subsubsection{Selecting pages}
There are a number of interesting pages in \verb|nasty.dvi|.
Use ``Previous Page'', ``Next Page'' or ``Go to Page\,\ldots'' to
have a look at some of them.
Note that the current DVI/\TeX\ page numbers are always displayed in the
view window's title bar.  Here are some points of interest:
\begin{itemize}
\item
The current scale factor and page location will only change if the selected page
is off the paper, in which case \OzTeX\ will beep and display a full view.
Pages 13 to 15 illustrate this behaviour.
When you move from such a page to a normal page, \OzTeX\ switches back to the
default view.
\item
\OzTeX\ may take a little while to interpret and display a selected page,
depending on how complicated it is.  Hit Command-dot if you get bored.
\item
Page 3 has examples of \verb|\special| commands.
\OzTeX\ is able to preview included files of type PICT, PNTG or EPSF;
see section~\ref{graphics} for more information.
The location of each \verb|\special| is indicated by a small marker.
Note that the size of this marker does not change as you zoom in or out.
\item
Page 9 uses a couple of PostScript fonts; see section~\ref{ps-fonts}.
\item
All the fonts used on page 12 are deliberately missing.
\item
Page 16 has examples of bad \verb|\special| commands.
\end{itemize}
When you have finished previewing the DVI file just click in the view window's
close box.  The view window is also closed automatically when you
run \TeX, print a DVI file or load a configuration file.
\subsubsection{Keyboard short cuts}
\label{shortcuts}
\OzTeX\ provides a number of keyboard short cuts to make it easier to
preview a DVI file:
\begin{itemize}
\item
Type ``\verb|o|'' to bypass the view dialog and open the most recently viewed
DVI page (or page 1 if you haven't viewed anything yet).  \OzTeX\ will also
restore the scale factor and location you last used.
If you type ``\verb|o|'' while \TeX\ is running then \OzTeX\ will
view the DVI file at the end of the run.
\item
Type ``\verb|i|'' to see page info.
\item
Type ``\verb|g|'' to go to a given page and switch to the default view.
\item
Type ``\verb|<num>g|'' to go to DVI page \verb|<num>|.
``\verb|-1g|'' will go to the last page, ``\verb|-2g|'' to the 2nd last page, etc.
``\verb|99g|'' will also go to the last page if there are fewer than 99 pages.
\item
Type ``\verb|<num>t|'' to go to \TeX\ page \verb|<num>|.
``\verb|99t|'' will only go to \TeX\ page 99 if it exists;
if not, \OzTeX\ beeps and the page selection dialog appears.
\item
Type ``\verb|b|'' to move to the bottom of the previous page without changing
the current scale or horizontal position.
\item
Type ``\verb|n|'' to move to the top of the next page without changing the
current scale or horizontal position.
\item
Type ``\verb|[|'' to go back one link.
\item
Type ``\verb|]|'' to go forward one link.
\item
Type ``\verb|f|'' to change the scale to full view.
\item
Type ``\verb|a|'' to change the scale to actual size.
\item
Type ``\verb|h|'' (or Home) to move to the first page and switch to the default view.
\item
Type ``\verb|e|'' (or End) to move to the last page and switch to the default view.
\item
Hit the space bar (or Page Down) to scroll forwards through a document.
\item
Hit the Delete key (or Page Up) to scroll backwards.
\item
Hit the Return key to bring either the view window or the \OzTeX\ window
to the front.
\item
Type ``\verb|d|'' to toggle the dither option (System~7 or later is required).
\item
Type ``\verb|w|'' to close the view window.
\end{itemize}
Note that all the Command-key items in the View menu have matching short cuts.
\subsection{Printing a DVI file}
Before printing a DVI file it is a good idea to select ``Page Setup'' from the
File menu and make sure the paper size and orientation are correct.
To print \verb|nasty.dvi| choose either of the top two items in the File menu. % XREF
Choosing the second item simply avoids the open-file dialog.
\OzTeX\ tries to support all Macintosh printers, but it also tries
to take advantage of the sophisticated features available in PostScript printers.
This has often meant going against Apple's guidelines for device-independent
printing, so \OzTeX's printing code has had a long and interesting history!
All this is half-explanation and half-apology for what might seem to be an
unnecessarily complicated printing strategy.
\OzTeX\ supports three methods of printing a DVI file:
\begin{enumerate}
\item Non-PostScript printing.
\item Low-level PostScript printing.
\item Standard PostScript printing.
\end{enumerate}
The printing method chosen by \OzTeX\ depends on whether or not the current
printer is a PostScript device, and the current state of the File menu's
``Use Standard PostScript'' flag.
For the bottom two methods,   % XREF
\OzTeX\ uses a built-in version of Tom Rokicki's \dvips\ program
to convert a DVI file into PostScript;
see section~\ref{dvips-sec} for details about \dvips.
\subsubsection{Non-PostScript printing}
\label{nonpsprint}
If the current printer is not a PostScript device
then the ``Use Standard PostScript'' flag is ignored.
\OzTeX\ will open the DVI file and display a printer-specific dialog.
(If the current \verb|printing_resolution| value does not match the actual
resolution of the printer then you'll first be warned about possible
scaling problems; see section~\ref{scaling-probs}.)
For example, if the current printer is a StyleWriter then you'll get
a dialog like this:
\vbox to 2.45in{\vfil
\noindent\hskip 0.65in\special{pntg=nonpsprint scale=0.72}}
\bigskip
\noindent
The dialog box lets you change various options specific to the current printer.
\OzTeX\ adds some extra items at the bottom of the dialog:
\begin{itemize}
\item
Some text showing the first and last DVI/\TeX\ pages.  This information can
be useful when entering DVI page numbers in the ``From'' and ``To'' edit boxes.
\item
Edit boxes for changing the page increment and DVI magnification.
\item
Check boxes for reversing the page order, showing statistics
and making missing PK fonts.
\end{itemize}
Click on the Print button or hit the Return key to start printing.
At any time while \OzTeX\ is printing you can switch to another application
and \OzTeX\ will continue to print in the background.
\subsubsection{Low-level PostScript printing}
\label{lowpsprint}
If the current printer is a PostScript device
and ``Use Standard PostScript'' is \emph{not} ticked
then \OzTeX\ will start up \dvips\ and display the following dialog:
\vbox to 2.4in{\vfil
\noindent\hskip 1.0in\special{pntg=lowpsprint scale=0.72}}
\bigskip
\noindent
This dialog box lets you change a variety of print options.
The option you'll want to change most often is the page range.
The two scroll bars control the first and final pages.
\OzTeX\ prevents you from choosing a first page greater than the final page.
Play around with the scroll bars but restore their values so that every
page will be printed.
A number of check boxes let you change
the paper orientation (landscape or portrait),
the page order (reverse or normal),
whether or not PK fonts should be compressed
(useful at high resolutions or when very large fonts are used),
the paper source (manual feed or normal input tray),
whether or not to show statistics (equivalent to \verb|-d7|),
and whether or not to make missing PK fonts.
Any change to a check box option will be remembered the next time you
print a DVI file, unless you decide to Cancel the dialog.
The pop-up menu makes it easy to add extra \dvips\ options.  Selecting an
option from the menu will automatically append it to the current options.
If an option requires a parameter then \OzTeX\ selects the parameter template
so you can type in the desired number, string, or whatever.
You can of course ignore the pop-up menu and just type in your options.
(Details on all \dvips\ options can be found in the DVIPS item
in the Help menu.)
Two radio buttons let you send the output to the printer or to a file.
We'll use the printer, so click on the Print button (or hit Return).
You can't actually print every page in \verb|nasty.dvi| because there
is a deliberate error that makes this impossible.
The first 11 pages should not cause any problems (assuming you're using
A4 paper) but the rest will generate nearly every type of error message
you're ever likely to encounter.
You should eventually get up to page~17   % XREF
where a deliberate PostScript error in a \verb|\special| file will
prevent any further pages being printed.
\subsubsection{Standard PostScript printing}
\label{stdpsprint}
If the current printer is a PostScript device
and ``Use Standard PostScript'' \emph{is} ticked then \OzTeX\ will
start up \dvips\ and display the standard dialog for that printer:
\vbox to 2.7in{\vfil
\noindent\hskip 0.6in\special{pntg=stdpsprint scale=0.72}}
\bigskip
\noindent
Below the normal options for the current printer, \OzTeX\ adds some extra items.
They are the same ones described in the dialog box for non-PostScript printing
in section~\ref{nonpsprint}, except for the page increment which has been
replaced by a pop-up menu for entering \dvips\ options.
The items in this pop-up menu are slightly different to those in the
low-level dialog because some options either cannot be used or don't make
sense when merging \dvips\ output with the PostScript code generated by
Apple's LaserWriter drivers.
NOTE: Due to incompatibility problems, the pop-up menu is not available
in the print dialog for LaserWriter 8.4.x or later.
Click on the Print button or hit the Return key to start printing.
Note that \dvips\ has to go through all selected DVI pages first and
determine font and character usage.  All the PK character bitmaps and
PostScript font files are then downloaded at the beginning, so the
first page in a long document might take a while to be printed.
Although there are some advantages to using standard PostScript,
such as being able to select printer-specific options like which
input tray to use, there are significant disadvantages.
A limitation in LaserWriter drivers older than version~8 causes a
PostScript error when printing all but the simplest of DVI files.
\OzTeX\ is able to predict when this error is likely to occur
and will display a suitable warning message.
Also, the standard PostScript code takes longer to print.
If you want to use \OzTeX's more efficient low-level printing
method then leave ``Use Standard PostScript'' unticked.
\OzTeX's low-level code works under QuickDraw~GX
on both AppleTalk and serial printers.
Another advantage is that any PostScript error messages should
appear in the \OzTeX\ window (on some printers, like the
LaserWriter Select 310, you might need to send
{\tt :PS-files:geterrors.ps} first).
\subsection{Positioning pages correctly}
For your DVI output to appear in precisely the right location on the paper,
the \TeX\ origin must be exactly one inch in from the top and left paper edges.
Page 2 in \verb|nasty.dvi| contains a thick rule with its top left
corner exactly at the \TeX\ origin.
If the output from a non-PostScript printer shows a significant discrepancy
then adjust the \verb|horizontal_offset| and/or \verb|vertical_offset| in
the {\tt Default} config file to shift the origin to the correct position.
These offset parameters are \emph{not} used by \dvips, so to adjust the
origin for a PostScript printer you could add a line containing
something like ``\verb|O 3mm,-2mm|'' to the {\tt config.ps} file
in {\tt :DVIPS:Inputs:}.
If your printer is set up for US~Letter paper then before adjusting
the offsets you should first change the {\tt Default} file's \verb|paper_width|
to \verb|8.5in| and the \verb|paper_height| to \verb|11in|.
Note that the current paper dimensions \emph{are} passed on to \dvips.
If you use more than one printer then you will probably need a separate
configuration file for each printer.
You might also need to create a separate configuration file
for landscape printing.
\subsection{Continuing from where you left off}
That's the end of the guided tour.  One more useful feature to note is that
\OzTeX\ remembers most of your settings in a preferences file called \ozprefs.
Some of the important settings include window sizes and locations,
the \TeX\ file, the format, the DVI file
and the most recently previewed DVI page, including the scale and location
for use by the ``\verb|o|'' keyboard short cut.
The next time \OzTeX\ starts up it will recall
all this information so you can continue working from where you left off.
(Double-clicking on a file to start up \OzTeX\ will of course
override some of this information.)
If you want to restore all settings to their default values then simply
delete \ozprefs\ or move it into a folder where \OzTeX\ can't find it.
The next time \OzTeX\ starts up it will create a new \ozprefs\ file
and initialize it with default settings.
\ozprefs\ is created in the Preferences subfolder under System~7
or later, or in the System folder itself under earlier System versions.
If you like, you can move \ozprefs\ to the same folder as \OzTeX;
I prefer this because it simplifies my backup process.
Note that \OzMF\ and \OzMP\ have their own {\tt Prefs} files.
\newpage
\section{\OzTeX's menus}
Let's go through each menu and discuss each item in detail,
concentrating on the things not mentioned in the guided tour.
\subsection{The File menu}
\label{file-menu}
\subsubsection*{Print DVI\,\ldots}
Prints a selected DVI file.
After selecting the DVI file you'll be presented with a dialog box that
depends on the current printer and the setting of ``Use Standard PostScript''
(described below).   % XREF
Non-PostScript printing is discussed in section~\ref{nonpsprint}.
Low-level PostScript printing is discussed in section~\ref{lowpsprint}.
Standard PostScript printing is discussed in section~\ref{stdpsprint}.
Hit Command-dot at any time to cancel printing, or switch to another
application and \OzTeX\ will continue to print in the background.
\subsubsection*{Print ?.dvi}
Prints the indicated DVI file.
This item is initially disabled; the file name changes after you
select a DVI file via ``Print DVI\,\ldots'' or ``View DVI\,\ldots'',
or create a DVI file by running \TeX\null.
\subsubsection*{Print Text\,\ldots}
Prints a selected text file.
If \OzTeX\ decides to use low-level PostScript printing then
this file is sent after the \textpro\ file which is kept in the
\psfiles\ folder.  If you know a little about PostScript then
you might like to modify \textpro\ to suit your own needs.
For example, the tab width is defined in \textpro.
If \OzTeX\ uses standard PostScript printing, or non-PostScript printing,
then you'll get a printer-specific dialog with an extra edit box that
lets you specify the tab width.  The default tab width is 3.
Text files are printed using 10\,pt Courier.
\subsubsection*{Page Setup\,\ldots}
\label{page-setup}
The ``Page Setup'' dialog lets you select various printer-specific options that
will be used in standard PostScript printing or non-PostScript printing.
If you select OK then the dialog settings are remembered for later \OzTeX\ sessions.
However, if the Chooser is used to select a different printer then the settings
will be restored to default values for the new printer.
Note that in low-level PostScript printing, \OzTeX\ ignores the ``Page Setup''
settings.  In this case the paper size is determined by \OzTeX's
\verb|paper_width| and \verb|paper_height| parameters.
\subsubsection*{Use Standard PostScript}
\label{usestdps}
Tick this flag if you want to use the standard Mac print dialogs when printing
a DVI file or text file to a PostScript printer.  (However, if the currently
chosen printer is \emph{not} a PostScript device then \OzTeX\ ignores this flag
and switches to non-PostScript printing.)
If ``Use Standard PostScript'' is ticked, then remember that ``Page Setup''
must be used to select the paper size and orientation before printing
a DVI file or text file.  You can also select other handy features like
2-up printing if you have the LaserWriter~8 print driver.
\subsubsection*{Send PostScript\,\ldots}
Sends a selected text file, presumably a PostScript program, to the current
printer.  (If it isn't a PostScript printer then you won't get far!)
The \psfiles\ folder contains a number of interesting files that can be
sent to any PostScript printer.
If a PostScript file is sent to spooling software rather than directly to the
printer then you probably won't see any messages sent back to the \OzTeX\ window.
In such an environment it's a good idea to send \verb|errhandler.ps| first
so that any PostScript errors will be printed on paper.
\subsubsection*{Send ?.ps}
Sends the indicated PostScript file to the current printer.
This item is initially disabled; the file name changes after
a PostScript file is created by \dvips\ or one of the PS tools.
\subsubsection*{Save All Text\,\ldots}
Saves the entire contents of the \OzTeX\ window to a given text file.
The {\tt Default} config file sets the file name to \oztext.
This item is disabled if the \OzTeX\ window is empty or not in front.
\subsubsection*{Delete}
Lets you delete files ending in a given string selected from a sub-menu.
The open-file dialog has a ``Do all files'' button that lets you delete
all such files in the selected folder.  Use this feature with caution!
(A note to ResEdit hackers: you can modify the Delete MENU resource
to create your own menu of suffixes.)
\subsubsection*{Quit}
Quits \OzTeX.
\subsection{The Edit menu}
\label{edit-menu}
\OzTeX\ does not have an integrated text editor, so most of the standard
editing items are normally disabled.  You can however use the Copy item
to copy selected text from the \OzTeX\ window to the Clipboard.
\subsubsection*{Copy All Text}
Copies the entire contents of the \OzTeX\ window to the Clipboard.
Note that you don't have to select all the text first.
This item is disabled if the \OzTeX\ window is empty or not in front.
\subsubsection*{Font}
Selects the screen font used to display text in the \OzTeX\ window.
You can choose from any of the currently installed fonts, but for best
results it is advisable to use a fixed-width font like Monaco or Courier.
This item is disabled if the \OzTeX\ window is not in front.
\subsubsection*{Size}
Selects the point size of the font used in the \OzTeX\ window.
(The available sizes are stored in a MENU resource in \OzTeX,
so use ResEdit if you want to change the supplied values.)
This item is disabled if the \OzTeX\ window is not in front.
\subsubsection*{Choose Editor\,\ldots}
This item is only enabled under System~7 or later.
It lets you select the target application (presumably an editor) to which
\OzTeX\ will send ``open file'' events.  If the chosen application can
receive such events then \OzTeX\ remembers its name and location for later use
(see below).   % XREF
\subsubsection*{Select Error Line}
This item is only enabled under System~7 or later.
If ticked, this flag tells \OzTeX\ to include an extra parameter in the
``open file'' event sent when you type ``\verb|e|'' in response to
\TeX's ``\verb|?|'' prompt (which normally occurs after a \TeX\ error).
The extra parameter specifies the line number so your editor can
automatically select the line containing the error.
However, some editors can't handle the extra parameter and won't even open
the file.  You will need to experiment with your editor to see if it can
select the error line; if it can't then make sure ``Select Error Line'' is
\emph{not} ticked.  Note that AlphaLite supports the extra parameter.
\subsubsection*{Edit ?.tex}
This item is only enabled under System~7 or later.
If selected, \OzTeX\ will send an ``open file'' event to your current editor.
\OzTeX\ will launch the editor if necessary.
This item normally contains the name of the most recently typeset file
(it will always match the file shown in the \TeX\ menu's 2nd item).
\subsection{The \TeX\ menu}
\subsubsection*{\TeX\,\ldots}
Typesets a selected input file using the current format
(or the format on the first line of the input file; see below).   % XREF
The \OzTeX\ window acts like a terminal during a \TeX\ session.
One of the nicest things about \TeX\ is that it behaves the same way
on a large range of different computer systems.
Virtually everything you read in \texbook\ will apply to the version
of \TeX\ run by \OzTeX, and the same goes for Leslie Lamport's \LaTeX\ book
if you use that format.
A few extra features have been added in \OzTeX:
\begin{itemize}
\item
\TeX\ looks for ``\verb|%&format|'' on the first line of a selected
input file and, if present, uses the given format regardless of the
currently ticked format in the \TeX\ menu.
\item
Input files can have either Return or Linefeed as the end-of-line character.
This means that \TeX\ can read Unix text files unmodified and thus
avoid spurious \verb|buf_size| overflow errors.
\item
Most of \TeX's capacity parameters are set at run-time in
a configuration file rather than at compile-time.
If you get a ``capacity exceeded'' error then
you should be able to overcome the problem by increasing the appropriate
parameter (see section~\ref{capacity}).
\item
\TeX\ will look for input files in the current folder first, then in
the folders specified by the \verb|input_folders| parameter.
Similarly, when looking for TFM files, \TeX\ will look in the current folder
first and then in the folders specified by the \verb|tfm_folders| parameter.
\item
New text files created by \OzTeX\ will have your chosen editor's signature,
so double-clicking on a new {\tt .log}/{\tt .aux} file will open it in the editor.
However, \OzTeX\ won't change the signature of an existing file, so if you
want to double-click on a {\tt .log} file to start up \OzTeX, use ResEdit
or some other utility to change the file's creator signature to ``OTEX''.
\item
You can interrupt a \TeX\ session at any time by typing Command-dot.
Depending on what it is currently doing, \TeX\ usually responds immediately
with a suitable message and the ``\verb|?|'' prompt.
If you hit Command-dot at this stage
(or whenever the block cursor is visible) then \TeX\ will immediately abort.
\item
\TeX\ will continue typesetting in the background if you switch to another
application.
\end{itemize}
\subsubsection*{\TeX\ ?.tex}
Typesets the indicated input file using the current format
(or the format on the first line of the input file).
\OzTeX\ remembers the most recently typeset file.
\subsubsection*{INITEX}
Runs \initex, a special version of \TeX\ normally used to create format files;
see section~\ref{fmt-sec}.
\subsubsection*{List of formats}
The items below \initex\ are specified by the \verb|format_files| parameter.
The {\tt Default} config file sets the formats to
{\tt LaTeX}, {\tt AMSTeX} and {\tt Plain}.
The current format is indicated by a tick and will be the one used when you
typeset a file, although this will be overridden if the first line of the
file starts with ``\verb|%&format|''.
To change the current format, simply select a different format item.
\OzTeX\ automatically ticks the first format found when loading a
config file containing \verb|format_files|, so it's a good idea to place
your preferred format first.
\subsection{The View menu}
\label{view-menu}
\subsubsection*{View DVI\,\ldots}
Previews a selected DVI file.
\OzTeX\ will open the view window and set its title to the name of the
selected DVI file.
You'll then be presented with a dialog box (see page~\pageref{viewdlg})
that lets you choose various viewing options:
\begin{itemize}
\item
The initial page to display.
A scroll bar allows you to locate any page in the DVI file.
The left and right arrow keys can be used to move the thumb box.
You can also type in a specific DVI page or \TeX\ page; if the given number
is valid then the other page number is updated and the scroll bar repositioned.
If there is only one page in the DVI file then the scroll bar will be inactive.
\item
The paper orientation (landscape or portrait).
Any change to this option will be remembered the next time you
view a DVI file, unless you Cancel the dialog.
The check box setting will also be used in the dialog for
low-level PostScript printing.
\item
Prescanning for color \verb|\specials|.
You only need to enable this option if your document uses color;
see section~\ref{color}.
\item
The next two check boxes can be used to tell \OzTeX\ to
ignore bad \verb|\special| commands and/or missing fonts.
It is a good idea to select both these check boxes when previewing a DVI file
created by another \TeX\ system, otherwise you might get a lot of annoying
warning messages.  \OzTeX\ remembers these check box settings.
The previewer recognizes all \dvips-specific \verb|\special| commands
and silently ignores those it can't handle (like rotation and other commands
that use raw PostScript code).  Ditto for {\tt tpic} \verb|\specials|.
This means that most people should never need to tick the
``Ignore bad \verb|\specials|'' option.
\item
The second last check box can be used to make missing PK fonts
(but it will be ignored if ``Ignore missing fonts'' is selected).
\OzTeX\ remembers the check box setting.
See section~\ref{mf-sec} for more details.
This option is only available under System~7 or later.
\item
The last check box tells \OzTeX\ whether or not to dither the bitmaps used
for PK fonts and \verb|\special| images.  If you have a color or gray-scale
monitor then dithering should improve the readability of PK fonts.
\OzTeX\ remembers the check box setting.
Dithering is only available under System~7 or later.
\item
The DVI magnification
(expressed as an integer 1000 times the desired magnification).
You should only alter the default value if you plan to print
the DVI file at a different magnification.
See Chapters~4 and 10 in \texbook\ for details.
A document using only PostScript fonts can be viewed/printed at
almost any magnification (\OzTeX\ allows values from 1 to 10000).
Note that \OzTeX\ does not remember any change to the DVI magnification.
\end{itemize}
If you Cancel the dialog then \OzTeX\ will close the view window.
If you select the View button then the current DVI/\TeX\ page numbers will be
appended to the DVI file name in the view window's title bar and
\OzTeX\ will locate the requested page, interpret it and display it.
The initial scale factor and page location will be set to values determined
by the default view (see section~\ref{def-view}).
However, if any part of the page is off the paper then \OzTeX\ will beep and
show a full view instead (see the ``Full View'' item below).   % XREF
\subsubsection*{View ?.dvi}
Previews the indicated DVI file.
Exactly the same sequence of events described above will occur.
This item is initially disabled; the file name changes after you
select a DVI file via ``Print DVI\,\ldots'' or ``View DVI\,\ldots'',
and after \TeX\ creates a DVI file.
\subsubsection*{Show \OzTeX\ {\rm or} Show View}
Brings either the \OzTeX\ window or the view window (if open) to the front.
The Return key is a keyboard short cut for this menu item.
\subsubsection*{Page Info}
Displays information about the current DVI page in the \OzTeX\ window,
bringing it to the front if necessary.
This item is disabled if the view window is closed.
The information displayed includes:
\begin{itemize}
\item
The ten \TeX\ page counters stored with the current page (trailing
counters with zero values are not shown).
\item
The total number of pages, viewing resolution, DVI magnification and
paper dimensions.
\item
A list of all the fonts used in the entire DVI file.
For each font appearing on the current page \OzTeX\ will show the total number
of characters used.
Note that the order of fonts may change as you move from page to page;
\OzTeX\ sorts the list so that all fonts actually used on the current page
appear first.
A PostScript font is indicated by its corresponding TFM path name
and the requested point size.
A PK font is indicated by a PK path name.
Missing PK or TFM files are flagged by the message ``\verb|DOES NOT EXIST|''\null.
Missing screen fonts are flagged by the message ``\verb|NO SCREEN FONT|''.
\item
A list of all virtual fonts used in the DVI file.
Those used on the current page are flagged by a comment.
\item
The number of rules on the current page.
\item
The location and argument of each \verb|\special| command on the page.
The location is expressed in terms of \OzTeX's paper coordinate system;
see section~\ref{paper-coords}.
If the \verb|\special| command includes a valid PICT/PNTG/EPSF file then
the width and height of the image's bounding box is also displayed.
\end{itemize}
Note that if the DVI file uses virtual fonts then ``Page Info'' won't
necessarily detect all missing PK files.  A missing PK file referenced
in a virtual font will only be detected if a character requiring that
PK file is used somewhere on the current page.
Use \dvips\ and create a {\tt .ps} file if you want to detect all
missing PK fonts.
\subsubsection*{Previous Page}
Displays the previous DVI page.
This item is disabled if the view window is closed or currently displaying
the first page.
\subsubsection*{Next Page}
Displays the next DVI page.
This item is disabled if the view window is closed or currently displaying
the last page.
\subsubsection*{Go to Page\,\ldots}
Brings up a dialog box allowing you to select any DVI page for display.
This item is disabled if the view window is closed or
if the DVI file only has one page.
\subsubsection*{Back Link}
Takes you back one Hyper\TeX\ link; see section~\ref{hype}.
\subsubsection*{Forward Link}
Takes you forward one Hyper\TeX\ link; see section~\ref{hype}.
\subsubsection*{Full View}
Changes the scale factor and location so that the entire DVI page and paper
edges are displayed in the middle of the current view window.
The scroll bars are disabled and the scale factor is set to its maximum value.
This item is disabled if the view window is closed or already displaying
a full view.
\subsubsection*{Actual Size}
Changes the scale factor so that the DVI page is displayed as near
as possible to its actual size.
The top left corner of the view window will still show the same page location,
unless shifting is necessary to keep within the scrolling limits.
This item is disabled if the view window is closed or already displaying
the page at its actual size.
The scale factor is actually set to the nearest integer equal to the viewing
resolution divided by the Mac screen resolution.
A likely calculation is $300/72 = 4.17$, so the scale factor is set to~4.
Because of this approximation, a 3\,in wide rule in your \TeX\ input file
won't appear exactly 3\,in wide in the view window.
If this is a serious problem then switch to a configuration file that sets
the viewing resolution to some multiple of the screen resolution;
you'll also need a matching set of PK files.
Note that $360 = 72 \times 5$.
\subsubsection*{Zoom In}
Halves the current scale factor.
The top left corner of the view window will still show the same page location,
unless shifting is necessary to keep within the scrolling limits.
This item is disabled if the view window is closed or already displaying
the page at minimum scale factor.
\subsubsection*{Zoom Out}
Doubles the current scale factor.
The top left corner of the view window will still show the same page location,
unless shifting is necessary to keep within the scrolling limits.
This item is disabled if the view window is closed or already displaying
the page at maximum scale factor.
\subsubsection*{Save as Default View}
Saves the current scale factor and page location as the default view
(see section~\ref{def-view}).
This item is disabled if the view window is closed.
\subsection{The Tools menu}
\label{tools-menu}
NOTE:
If the Option key is held down while selecting an item in the Tools menu
then \OzTeX\ will skip the open-file dialog and use the current DVI/PS file.
\subsubsection*{DVIPS\,\ldots}
This item is provided so you can always create a {\tt .ps}
file even if the currently chosen printer is non-PostScript.
When \dvips\ is called from the File menu then the default
destination is the current printer, but if called from the
Tools menu then the default destination is a file.
Note that Option-clicking on the Save button will skip the save-file
dialog and create {\tt foo.ps} in the same folder as {\tt foo.dvi}.
\subsubsection*{DVIDVI\,\ldots}
The DVIDVI item can be used to carry out pagination tricks on a
selected DVI file.
For more information, select the DVIDVI item in \OzTeX's Help menu.
After a DVI file has been selected, DVIDVI will look
in the \helpfiles\ folder for a file named ``\verb|DVIDVI examples|''.
If found, its contents will be displayed just before the {\tt Options}
prompt so that you can cut and paste the examples.
\subsubsection*{DVIcopy\,\ldots}
Selects a DVI file and replaces all virtual fonts with actual fonts.
See section~\ref{vf-sec} for information about virtual fonts.
Most people won't need to use DVIcopy because \OzTeX\ automatically
resolves all references to virtual fonts.
If you decide to use DVIcopy then you need to be aware of a potential
problem; see the DVIcopy item in \OzTeX's Help menu for details.
\subsubsection*{PSbook\,\ldots}
PSbook rearranges pages from a PostScript file into ``signatures''
for printing books or booklets, creating a new PostScript file.
\subsubsection*{PSnup\,\ldots}
PSnup reads a selected PostScript file and creates a new PostScript file
with multiple logical pages on each physical sheet of paper.
\subsubsection*{PSselect\,\ldots}
PSselect selects pages from a PostScript file, creating a new PostScript file.
\subsubsection*{PStoPS\,\ldots}
PStoPS rearranges pages from a PostScript file, creating a new PostScript file.
\bigskip
\noindent
The above PS tools are Mac implementations of
Angus Duggan's utilities for manipulating PostScript files
(usually created by \dvips).
For more information about each tool, select the corresponding
item in the Help menu.
After a PostScript file has been selected, each tool will look
in the \helpfiles\ folder for a file named ``\verb|<tool> examples|''.
If found, the contents will be displayed in the \OzTeX\ window
just before the {\tt Options} prompt so that you can cut and paste
the examples.  Feel free to remove/rename/edit the supplied files.
DVIDVI and the PS tools can be asked to create an output file with the
same name as the input file (\OzTeX\ temporarily renames the input file).
They will also repeat the {\tt Options} prompt if an error is detected
in the given options, so there is no need to select the input and output
files again.
\subsection{The Config menu}
\subsubsection*{Show}
Shows the current values of configuration parameters in the \OzTeX\ window.
You can choose to show all parameters or only certain subsets.
The output is displayed with the correct syntax for a configuration file;
this makes it easy to create a new configuration
file by simply saving the \OzTeX\ window.
\subsubsection*{Load Config\,\ldots}
Lets you select and load a configuration file
(not necessarily in the \configs\ folder) without having to add it to the
list of configuration files in the {\tt Default} file.
This means you don't have to clutter up your Config menu with rarely used
config files.
\subsubsection*{Default}
Loads the {\tt Default} configuration file, resetting all parameters
to their default values.
\OzTeX\ will also load any config files whose names start with ``\verb|+|''.
\subsubsection*{Other configuration files}
\label{other-configs}
The remaining items in the Config menu are determined by the
\verb|config_files| parameter in the {\tt Default} file.  The items must
correspond to the names of text files in the \configs\ folder.
Selecting one of these items causes the corresponding configuration file
to be loaded.  A tick appears next to the most recently loaded file.
Here is a brief description of all the non-default config files
supplied with \OzTeX:
\begin{description}
\item[\tt StyleWriter]
configures \OzTeX\ for the StyleWriter printer.
The printing and viewing resolutions are set to 360
and both modes to {\tt stylewriter}.
The \verb|reverse_page_order| parameter is set to {\tt true} because this printer
stacks pages face up.
\item[\tt ImageWriter]
configures \OzTeX\ for the ImageWriter printer.
The printing and viewing resolutions are set to 144
and both modes to {\tt imagewriter}.
\item[\tt Linotronic]
configures \OzTeX\ for a Linotronic typesetter.
The printing resolution is set to 1270 and the mode to {\tt linohi}.
\item[\tt 600 dpi printer]
configures \OzTeX\ for a 600\,dpi printer.
The printing resolution is set to 600 and the mode to {\tt ljfour}.
This mode is suitable for a HP LaserJet~4.
If you have a different type of 600\,dpi printer then
you might need to use a different mode to get better looking fonts.
\item[\tt A5 Portrait]
sets the paper dimensions for A5 paper in portrait mode.
\item[\tt A4 Landscape]
sets the paper dimensions for A4 paper in landscape mode.
\item[\tt US Letter]
sets the paper dimensions for US Letter paper in portrait mode.
\item[\tt View at 144 dpi]
sets the viewing resolution to 144 and the mode to {\tt imagewriter}.
Characters from 144\,dpi PK files scale better on most Mac screens
(normally 72\,dpi).  Previewing will also be faster and use much less memory.
\item[\tt View CM using PS]
tells \OzTeX\ to preview Computer Modern text fonts using the nearest
``equivalent'' PostScript screen fonts.
If you have the corresponding TrueType or ATM (Adobe Type Manager) fonts,
your text will be much more readable, apart from some strange kerning
and the odd incorrect character (e.g., you won't see any ``ffi'' ligatures).
The viewing resolution is set to 360 ($5 \times 72$) so that ``Actual Size''
dimensions will be accurate.
\item[\tt Add BaKoMa Fonts]
updates the current list of PostScript fonts so that
\OzTeX\ can use the BaKoMa fonts created by Basil Malyshev.
These fonts are free PostScript and TrueType versions of Computer Modern.
They can be obtained by ftp from any CTAN site.
See the comments in the config file for more details.
\item[\tt Add CM/PS Fonts]
updates the current list of PostScript fonts so that
\OzTeX\ can use the CM/PS fonts created by Blue Sky Research.
The CM/PS fonts are PostScript versions of the Computer Modern fonts.
These are also in the public domain and available from CTAN sites.
However, you need to install ATM to get nice-looking screen fonts.
\item[\tt Add Lucida Fonts]
updates the current list of PostScript fonts so that
\OzTeX\ can use the Lucida fonts available from Y\&Y\null.
Lucida is an alternative to Computer Modern, including math fonts, in
Adobe Type~1 format.
\item[\tt Add MathTime Fonts]
updates the current list of PostScript fonts so that
\OzTeX\ can use the MathTime fonts available from The \TeX plorators Corporation.
MathTime is a set of math fonts suitable for use with Times Roman.
\end{description}
Some config files do not appear in the Config menu but can be
loaded from the \configs\ folder:
\begin{description}
\item[\tt Remove Help Menu]
removes \OzTeX's Help menu.
\item[\tt LaTeX209.config]
and {\tt LaTeX.config} can be used to configure \OzTeX\ to typeset documents
with either the old \LaTeX\,2.09 format or the new \LaTeX\ format;
see section~\ref{oldlatex}.
\end{description}
You can of course modify any of these config files to suit your own needs.
If you've created your own config files and you think other people
might find them useful, please e-mail them to me and I'll
add them to the standard \OzTeX\ distribution.
\subsection{The Help menu}
The items appearing in this menu are set by the \verb|help_files| parameter
and must correspond to the names of text files in the \helpfiles\ folder.
Selecting an item from the Help menu simply causes the contents of the
corresponding file to appear in the \OzTeX\ window.
Feel free to add more items to the Help menu.
For example, you might like to create a file of \TeX/\LaTeX\ commands to refer
to while editing an input file.
If you want to add more help files, or modify the existing ones, then there
are a few things to watch out for.
Don't use tabs, and avoid long lines if you have a small screen.
If you create a new help file then remember to add it to the
\verb|help_files| list in the {\tt Default} file.
\section{Configuration files}
\label{config-sec}
\OzTeX, \OzMF\ and \OzMP\ can all be customized by changing
parameter values in configuration files.
The config files for \OzTeX\ are kept in the \configs\ folder.
The config files for \OzMF\ and \OzMP\ are kept in the
\configs\ subfolders inside the \mff\ and \mpf\ folders respectively.
\subsection{The required syntax}
\label{config-syntax}
A configuration file is a simple text file.
Follow these rules when editing a config file:
\begin{itemize}
\item
Blank lines are ignored.
Lines starting with ``\verb|%|'' are also ignored and can be used to include comments.
This is also true for lines starting with ``\verb|@|'', but in this case the rest
of the line is displayed in the application's main window.
\item
All other lines are parameters of the form ``keyword = value''.
Keywords are case insensitive.
Spaces or tabs around a keyword are ignored.
The same keyword can appear more than once in a config file;
later values override earlier ones.
\item
The ``\verb|=|'' character is optional, but I recommend you put it in.
Any spaces or tabs around ``\verb|=|'' are ignored.
The parameter value consists of one or more strings.
Multiple strings are separated by spaces or tabs, so use double quotes
around a string that includes spaces.
If only one string is required then the rest of the line is ignored.
\item
To avoid very long lines, use ``\verb-|-'' to split lines anywhere you like.
Upon reading a ``\verb-|-'', the application will ignore the rest
of the current line and continue reading from the next line.
The best place to use ``\verb-|-''
is where a space is allowed; that way you can safely indent the next line
to make the file more readable.
\item
A line starting with ``\verb|!|'' tells the application to stop reading
the config file.
This lets you add comments without having to start each line with ``\verb|%|''.
\end{itemize}
Note that the syntax is the same for all Oz\ldots\ applications,
but each one uses a different set of keywords.
\subsection{Path names}
Some parameters are used to tell each application where to find
certain files and folders.
The parameter values consist of one or more strings in the form of path names.
A path name can be a simple file name, or it can be a sequence of names
separated by colons that represent a valid location in your folder hierarchy.
If the path name ends with a colon then it specifies a folder, otherwise a file.
Path names must be enclosed in double quotes if they contain any spaces;
e.g., \verb|":My PK files:"|.
NOTE: Because \OzTeX's path names are also used by \dvips, you cannot use
a comma in those paths; if you do you'll get an error message when the
config file is loaded.  This is because commas are used to separate
\dvips\ search paths (the standard version of \dvips\ uses colons,
but they can't be used on the Mac).
Partial path names begin with a colon.  The first folder in such a path is
assumed to be in the same location as the application.  This is the best
way to specify folders and files because then you can move the entire
\OzTeX\ folder anywhere you like without having to change any path names.
Full path names begin with the name of a disk; e.g., \verb|HD:OzTeX:VF-files:|.
Each application will generate a warning message if a given path name
does not specify a known folder or file.
Note that under System~7 or later, aliased files are supported,
but not aliased folders.
\subsection{Default configuration files}
The Oz\ldots\ applications all read a config file called {\tt Default}
when starting up.
The supplied {\tt Default} files contain examples of all possible keywords.
They also contain detailed notes (at the end of each file) discussing how
the important parameters are used and other handy tips.
Please read these notes before making changes to a {\tt Default} file.
After loading a {\tt Default} file, each application will also load any
files in the \verb|config_files| list whose names start with ``\verb|+|''.
So, rather than modify the {\tt Default} file, you could create
a new config file called ``\verb|+Changes|'' which contains all your
changes to the default settings.
(You still need to edit the {\tt Default} file to add
``\verb|+Changes|'' to the \verb|config_files| list!)
This might make life easier when upgrading to future versions of \OzTeX.
Another good idea when modifying a {\tt Default} config file is to
isolate your changes in the one spot.  Because later use of a keyword
overrides an earlier use, the best location for all your changes is
just before the ``\verb|!|'' character at the start of the notes.
\subsection{Other configuration files}
The Oz\ldots\ applications all have a Config menu that lets
you switch rapidly from one configuration file to another.
In \OzTeX's case, this is especially useful if you have access to more
than one printer because each printer will probably require a separate
config file.  There are many other uses for config files;
see section~\ref{other-configs} for a brief description of the various
\OzTeX\ config files.  It is a simple matter to create your own files
and add their names to the \verb|config_files| list in the {\tt Default} file.
\newpage
\section{\LaTeX}
\OzTeX\ is distributed with the latest implementation of \LaTeX\ (formerly
called \LaTeX\,2e).  This new version of \LaTeX\ is described in
the 2nd edition of {\sl \LaTeX: A Document Preparation System\/} by Leslie Lamport
and {\sl The \LaTeX\ Companion\/} by Michel Goossens, Frank Mittelbach and
Alexander Samarin.  Both books are published by Addison-Wesley.
A number of important \LaTeX\ packages are provided.
The \verb|psnfss| package makes it easy to switch to PostScript text fonts
instead of Computer Modern.
The \verb|graphics|/\verb|graphicx| packages make it easy to include
Macintosh graphic files.
See the documentation and test files in the
\verb|PSNFSS| and \verb|Graphics| subfolders in \texinputs.
Other common packages are kept in the \verb|Tools| subfolder.
More information about \LaTeX\ can be found in the {\tt .tex} files
in the \verb|LaTeX| subfolder.
The \LaTeX\ system included with \OzTeX\ is \emph{not} a full distribution
(which is way too big for most \OzTeX\ users).
After installing the base files and the above packages,   % XREF
I deleted all the {\tt .ins}, {\tt .dtx} and {\tt .fdd} files,
as well as a few other files that were irrelevant for \OzTeX\ users.
If you need a file or package not provided in \OzTeX, then you can ftp it
from any CTAN site or mirror.  The following table should help:
\begin{tabbing}
\indent \= Subfolder in \texinputs\qquad \= \kill
\> Subfolder in \texinputs  \> Corresponding CTAN directory\\ [6pt]
\> {\tt LaTeX}               \> {\tt /tex-archive/macros/latex/unpacked}\\
\> {\tt Graphics}            \> {\tt /tex-archive/macros/latex/packages/graphics}\\
\> {\tt PSNFSS}              \> {\tt /tex-archive/macros/latex/packages/psnfss}\\
\> {\tt Tools}               \> {\tt /tex-archive/macros/latex/packages/tools}
\end{tabbing}
If you only need one or two files then ask me first and I might have a
copy I can send by e-mail, but you must be a registered \OzTeX\ user!
\subsection{Installing a new package}
\label{newpackage}
A \LaTeX\ package usually consists of a {\tt .ins} file, plus one or
more {\tt .dtx} files, and possibly some {\tt .fdd} files.
To install a package so that \OzTeX\ can use it,
run \LaTeX\ on the {\tt .ins} file.
This should create one or more files with extensions of the form
{\tt .sty}, {\tt .cfg} or {\tt .fd}.  Move these files into
a folder where \TeX\ can find them; a good idea is to put them
in a new subfolder in \texinputs.
If you want to read detailed documentation about the package then
use \LaTeX\ to process the {\tt .dtx} file and create a {\tt .dvi} file.
After using the package and verifying that everything works, you can
safely delete the {\tt .ins}/{\tt .dtx}/{\tt .fdd} files.
\subsection{Using \LaTeX\,2.09}
\label{oldlatex}
The old \LaTeX\,2.09 system is no longer distributed with \OzTeX\null.
\LaTeX\ users should seriously consider switching to the new \LaTeX; it can
typeset \LaTeX\,2.09 documents in ``compatibility'' mode.  If you have the
old \LaTeX\ system from an earlier version of \OzTeX\ and you want to use
it alongside the new \LaTeX, then the best approach is to edit the
{\tt LaTeX209.config} and {\tt LaTeX.config} files in the \configs\ folder
and make any necessary changes to the \verb|input_folders| list.
Just before running \TeX, \OzTeX\ will load \verb|<format>.config| if it
exists in the same folder as the input file, so move the {\tt .config}
files into the same folder(s) as your \LaTeX\ documents.
Make sure all your old \LaTeX\ documents start with ``\verb|%&LaTeX209|''
and the corresponding format file is called {\tt LaTeX209.fmt}.
Similarly, start all your new \LaTeX\ documents with ``\verb|%&LaTeX|''.
\section{Building format files}
\label{fmt-sec}
A format file contains a pre-compiled set of macros which \TeX\ can load in
very quickly.
To build a format file you need to run \initex\ (in the \TeX\ menu).
Here are the steps needed to create \verb|Plain.fmt|:
\begin{enumerate}
\item
Run \initex, wait for the ``\verb|**|'' prompt, type ``\verb|Plain\dump|''
and hit the Return key.
\initex\ will begin reading \verb|plain.tex| from the \verb|Plain| subfolder
in \texinputs.
\item
You'll eventually see the save-file dialog allowing you to save the format
information in the file and folder of your choice.
The default file shown will be \verb|Plain.fmt|.
The best location for format files is the \texformats\ folder.
\item
Note that {\tt Plain.log} is created in the current folder.
It's not needed, so delete it.
\end{enumerate}
The steps needed to create \verb|LaTeX.fmt| are very similar:
\begin{enumerate}
\item
Run \initex, wait for the ``\verb|**|'' prompt, type ``\verb|LaTeX.ltx|''
and hit Return (you don't need to add \verb|\dump|).
\initex\ will read \verb|latex.ltx| from the \verb|LaTeX| subfolder
in \texinputs.
\item
The dialog box will show \verb|LaTeX.fmt|, so just save this
file in the \texformats\ folder.
\item
Delete {\tt LaTeX.log} if you want to.
\end{enumerate}
Creating \verb|AMSTeX.fmt| is just as easy:
run \initex, type ``\verb|AMSTeX.ini|'' and
save \verb|AMSTeX.fmt| in the \texformats\ folder.
If you decide to rename any of the existing formats,
or add a completely new format,
then remember to update the \verb|format_files| list in your config file(s).
\subsection{Building big formats}
\label{big-fmt}
Some people with very large or complicated documents will need to build
big formats.  Here's how:
\begin{enumerate}
\item
Edit the {\tt Default} configuration file and locate the lines showing
large \TeX\ parameters; these are in the notes near the end of the file.
Copy these lines to a spot anywhere after the supplied \TeX\ parameters
(a good spot would be just before the first ``\verb|!|'').
\item
Click on the \OzTeX\ icon and use ``Get Info'' in the Finder's File menu
to set \OzTeX's preferred memory size to at least 3500K.
\item
Start up \OzTeX\ and follow the steps in the above section   % XREF
to rebuild all your formats.  Remember to save the {\tt .fmt} files
in the \texformats\ folder and thus replace all existing files.
\end{enumerate}
\subsection{Building custom formats}
\label{custom-fmt}
\initex\ can also be used to create custom formats to speed up
typesetting, especially for \LaTeX\ documents that use lots of packages.
Let's say you have a file called {\tt thesis.tex}.
Edit this file, cut out everything before \verb|\begin{document}|
and paste it into a new file called, say, {\tt thesis.ini}.
Set the current folder by selecting ``\TeX\,\ldots'', locating
{\tt thesis.ini} and hitting Cancel.
Select \initex, type ``\verb|&LaTeX thesis.ini\dump|''
and create {\tt thesis.fmt} in the current folder.
Add a new top line in {\tt thesis.tex} containing \verb|%&thesis|.
Now when you typeset {\tt thesis.tex} \OzTeX\ will load {\tt thesis.fmt}
and you should see a significant reduction in the typesetting time.
\section{Fonts}
\OzTeX\ can use the following sources of font information in the
process of typesetting, previewing and printing a document:
TFM files, PK files, VF files, PostScript font files
(for downloading non-resident fonts) and Macintosh screen fonts.
The following subsections discuss all these font sources in some detail.
\subsection{TFM files}
\label{tfm-sec}
A \TeX\ Font Metric file contains the crucial typesetting information for
a font, such as each character's height, depth and width.
The actual character images are not stored in a TFM file.
TFM files are the only source of font information used when running \TeX;
it doesn't need to know anything about character images to be able
to create a DVI file.
See \texbook\ if you want to know more about how
\TeX\ uses fonts, especially Chapter~4 and Appendix~F.
\OzTeX\ reads TFM files when printing or viewing a DVI file
containing any of the non-PK fonts listed in your configuration file.
The dummy TFM file specified in your configuration file will also be read
if a requested PK file can't be found
(PK files are discussed in section~\ref{pk-sec}).
\OzTeX\ will look for a TFM file in the current folder before looking in
the subfolders in \texfonts.
All the TFM files in the \verb|CM| subfolder belong to the
Computer Modern family of fonts (created by Donald Knuth using \mf\null).
The TFM files in the \verb|LaTeX| subfolder are used by \LaTeX\null.
The TFM files in the \verb|PS| subfolder correspond to PostScript fonts;
their names follow a scheme devised by Karl Berry in an attempt
to make \TeX\ input files more portable.  See section~\ref{ps-fonts} for
more information about these PostScript fonts.
\subsection{Creating new TFM files}
\label{new-tfm}
If the \OzTeX\ distribution doesn't provide a TFM file for a font you
would like to use then there are a number of things you can do:
\begin{enumerate}
\item
If you have access to the Internet then look for the TFM file in the
nearest CTAN site (see the ``Related Software'' item in the Help menu).
If the font is called \verb|foo| then look for \verb|foo.tfm|.
If it is a PostScript font then you might have to search a bit harder;
using Karl Berry's scheme it might be called something like \verb|pfo.tfm|.
If you find it, remember that a TFM file must be transferred as a binary file.
\item
If you can't find \verb|foo.tfm| then look for \verb|foo.mf|.
Such a file can be used by \mf\ to create \verb|foo.tfm|
(and a corresponding set of PK files).  See section~\ref{mf-sec}.
\item
If \verb|foo| is a PostScript font then look for \verb|foo.afm|.
An AFM (Adobe Font Metric) file contains very similar information to a TFM file.
Use {\tt AFM2TFM} in \OzMF\ to convert \verb|foo.afm| to \verb|foo.tfm|;
see the \dvips\ manual for detailed information about {\tt AFM2TFM}\null.
Alan Jeffrey's \verb|fontinst| package can also convert an AFM file
into a PL or VPL file which \OzMF\ can then convert into a TFM file
using {\tt PLtoTF} or {\tt VPtoVF}.
\item
As a last resort you could even create a PL file from scratch.
A very tedious job.
\end{enumerate}
Having found or created a new TFM file, you need to place it in a suitable
folder so that \OzTeX\ can find it.  If you put it in one of the subfolders
in \texfonts\ (or create a new subfolder) then you won't need to change the
\verb|tfm_folders| list in the {\tt Default} config file.
If the TFM file is for a PostScript font then you must add a suitable
entry to the list of fonts at the bottom of the {\tt Default} config file.
If you have a PostScript printer then \dvips\ needs a similar entry
added to {\tt psfonts.map} in {\tt :DVIPS:Inputs:}.
The examples in those files will show you what to do.
\subsection{PK files}
\label{pk-sec}
PK (packed pixel) files store the character images needed to print or view
a DVI file containing bitmap fonts; these are all the fonts \emph{not} listed
in your configuration file (or {\tt psfonts.map} in the case of \dvips).
Each bitmap font usually has a number of PK files,
each one representing the same font but at a different size.
This size is calculated as follows:
\hbox{\sl size} = \hbox{\sl resolution} \times \hbox{\sl magnification}
where {\sl resolution\/} is either the printing resolution or the
viewing resolution, and {\sl magnification\/} is the overall font magnification
(i.e., the DVI magnification times the individual font scaling).
The {\sl size\/} is then rounded up to the nearest integer and should
equal ($\pm 1$) one of the subfolder names in \pkfiles\ if you decide to keep
PK files of the same size in separate folders.
Although \TeX\ allows you to request a font at virtually any magnification,
it is obviously impossible to provide an infinite number of PK files.
The compromise solution is to provide a range of sizes for each font.
These sizes are in a geometric ratio based on powers of 1.2 and correspond to
\TeX's \verb|\magstep| values.
See Chapters~4 and 10 of \texbook\ for more details.
For example, assuming a {\sl resolution\/} of 300 and no document magnification:
\begin{tabbing}
\indent \= \verb|\font\rb=cmr10 scaled\magstephalf|\qquad \= $1.5\times1.2^{0.5}$\qquad \=\kill
\> \TeX\ input                             \> {\sl size}          \> PK file\\ [6pt]
\> \verb|\font\ra=cmr10|                   \> $300\times1.2^0$    \> \verb|cmr10.300pk|\\
\> \verb|\font\rb=cmr10 scaled\magstephalf|\> $300\times1.2^{0.5}$\> \verb|cmr10.329pk|\\
\> \verb|\font\rc=cmr10 scaled\magstep1|   \> $300\times1.2^1$    \> \verb|cmr10.360pk|\\
\> \verb|\font\rd=cmr10 scaled\magstep2|   \> $300\times1.2^2$    \> \verb|cmr10.432pk|\\
\> \verb|\font\re=cmr10 scaled\magstep3|   \> $300\times1.2^3$    \> \verb|cmr10.518pk|\\
\> \verb|\font\rf=cmr10 scaled\magstep4|   \> $300\times1.2^4$    \> \verb|cmr10.622pk|\\
\> \verb|\font\rg=cmr10 scaled\magstep5|   \> $300\times1.2^5$    \> \verb|cmr10.746pk|
\end{tabbing}
\TeX's \verb|\magnification| command has a cumulative effect on font scaling:
\begin{verbatim}
   \magnification=\magstep1            % document magnification = 1.2
   \font\bigrm=cmr10 scaled\magstep2   % font magnification = 1.44
\end{verbatim}
The font size is now $ 300 \times 1.2 \times 1.44 = 518.4 $,
so \OzTeX\ will use \verb|cmr10.518pk|.
Note that \LaTeX\ has no \verb|\magnification| command --- use
the \verb|11pt| and \verb|12pt| options to increase the size
of all fonts in a \LaTeX\ document.
\OzTeX\ uses a very flexible search scheme when looking for fonts.
If \verb|foo| is a PostScript font then \OzTeX\ looks for \verb|foo.tfm| in the
current folder before looking in \texfonts.
If \verb|foo| is not a PostScript font then \OzTeX\ looks for a PK file
using the list of templates specified by the \verb|pk_files| parameter.
For example, if the calculated size is 300 then \OzTeX\ will look for:
\begin{tabbing}
\indent \= 1. \verb|:PK-files:300:foo.300pk|\qquad \=\kill
\> 1. \verb|foo.300pk|               \> (in the current folder)\\
\> 2. \verb|:PK-files:foo.300pk|     \> (relative to the location of \OzTeX)\\
\> 3. \verb|:PK-files:300:foo.300pk| \> (ditto)
\end{tabbing}
In fact, at each step \OzTeX\ will also add and subtract 1 from 300
because rounding errors can occur in the size calculation.
If still not found, \OzTeX\ either gives up or calls \OzMF\ to make the
missing PK file (see section~\ref{make-pk}).
There is still another possibility to consider: a font name can include
an explicit location.  For example, your \TeX\ input file might contain
\verb|\font\xxx=:myfonts:foo|.  In this case \TeX\ will look for
\verb|:myfonts:foo.tfm| in the current folder;
that is, it expects to find a file called \verb|foo.tfm|
in a subfolder called \verb|myfonts|.
If not found then it gives up; it does not look for \verb|foo.tfm| in \texfonts.
Similarly, when you print or view the DVI file, \OzTeX\ will only look for
\verb|:myfonts:foo.tfm| if \verb|foo| is a PostScript font,
or for \verb|:myfonts:foo.300pk| (or \verb|301pk| or \verb|299pk|)
if \verb|foo| is a PK font.
Note that the use of an explicit font location is not recommended as it
decreases the portability of your \TeX\ input file.
Most of the PK files supplied with \OzTeX\ have been specifically generated
for a 300\,dpi, write-black laser printer (like the Apple LaserWriter).
If your printer doesn't have the same characteristics then you can
build new PK files using \OzMF\ as described in section~\ref{mf-sec}.
Note that the 300\,dpi PK files supplied with \OzTeX\ can also be used
on a 360\,dpi printer like the StyleWriter (because $360 = 300 \times 1.2$).
Two subfolders, \verb|394| and \verb|896|, complete the standard set of
magnifications for a 360\,dpi printer:
394 is the nearest integer to $360 \times 1.2^{0.5}$ and 
896 is the nearest integer to $360 \times 1.2^5$.
\subsection{PostScript fonts}
\label{ps-fonts}
To be able to view or print a PostScript font in a \TeX\ document,
\OzTeX\ needs to know certain information about the font,
especially the name of its corresponding TFM file.
This information is specified in a configuration file on lines between
\verb|begin_fonts| and \verb|end_fonts|; see the {\tt Default} file.
For \dvips\ however, information about PostScript fonts is obtained
from the {\tt psfonts.map} file in {\tt :DVIPS:Inputs:}.
The PostScript TFMs stored in the \verb|PS| subfolder in \texfonts\ are
meant to be used in conjunction with virtual font files
stored in the \vffiles\ folder
(section~\ref{vf-sec} has more information about virtual fonts).
These TFMs and VFs were created for the \verb|psnfss| package
by Sebastian Rahtz using Alan Jeffrey's \verb|fontinst| macros.
The fonts are supplied in both OT1 and T1 encodings.
The default encoding is OT1; this is the old \TeX\ text font encoding
described in \texbook.
The OT1 TFM/VF files have names ending in \verb|7t|.
The T1 (or Cork) encoding is the new \TeX\ text font encoding for
256-character fonts.
The T1 TFM/VF files have names ending in \verb|8t|.
See \verb|test0.tex| in the \verb|PSNFSS| subfolder in \texinputs\ for
how to select either encoding.
Note that virtual font names should not appear in a configuration file's
list of fonts, nor in {\tt psfonts.map}.
Only the corresponding ``raw'' fonts should be listed;
these are indicated by TFM names ending in \verb|8r|.
For example, when \OzTeX\ is processing virtual fonts in a DVI file
created with the \LaTeX\ \verb|times| package, it will use the commands
in {\tt ptmr7t.vf} to replace virtual characters from {\tt ptmr7t.tfm}
with actual characters from {\tt ptmr8r.tfm}.
\subsubsection{Reencoding PostScript fonts}
\label{reenc}
Most of the raw PostScript TFM files distributed with \OzTeX\ use
the \verb|8r| encoding.  The corresponding screen and printer fonts
do not use this encoding, so \OzTeX\ must be told to reencode the
screen fonts and \dvips\ must be told to reencode the printer fonts.
To reencode screen fonts (during previewing and non-PostScript printing),
\OzTeX\ uses information stored in encoding files.
The names of these files can appear in a config file's list
of PostScript fonts.
For example, the {\tt Default} config file includes an entry like this:
\begin{verbatim}
   ptmr8r   Times-Roman   Times   Mac8r.enc
\end{verbatim}
This tells \OzTeX\ to map character codes from {\tt ptmr8r.tfm} to
characters in the Times screen font using a mapping defined in {\tt Mac8r.enc}.
\OzTeX\ looks for encoding files in the \verb|ps_folders| list
(it does \emph{not} look in the current folder first).
For more information about encoding files, see section~\ref{enc-sec}.
Note that \OzTeX\ ignores the {\tt Times-Roman} field; it only serves
as a reminder of which printer font is represented by the rather
cryptic TFM name.
\goodbreak
To reencode printer fonts, \dvips\ gets the necessary information
from {\tt psfonts.map}.  The file supplied in {\tt :DVIPS:Inputs:}
contains lines like:
\begin{verbatim}
   ptmr8r   Times-Roman   "TeXBase1Encoding ReEncodeFont"   <8r.enc
\end{verbatim}
This tells \dvips\ to reencode {\tt ptmr8r.tfm} using an
encoding vector called {\tt TeXBase1Encoding}.
The vector is downloaded in a file called {\tt 8r.enc};
\dvips\ looks for {\tt 8r.enc} in the current folder first, then
in the \verb|ps_folders| list.
NOTE: Screen font reencoding is not as reliable as printer font reencoding
because some characters simply don't exist in Mac screen fonts.
(Font suitcases normally use the standard Mac text encoding
called ``Standard Roman Encoding''.)
This means that \OzTeX's preview might not match the output from \dvips.
Even worse, people with non-PostScript printers won't be able to print
the full range of reencoded characters.
The solution to this problem is to use a font editor/creator like
Fontographer to create suitable Mac fonts, or to purchase such fonts from
a supplier like Y\&Y.  (Y\&Y also sell a font manipulation package that
lets you create new font suitcases to match PostScript fonts, but it
is only available for DOS machines.)
\subsubsection{Downloading PostScript fonts}
Every PostScript printer has a certain set of resident fonts.
To see an alphabetical list of the PostScript fonts available in your current
printer, choose ``Send PostScript\,\ldots'' from the File menu,
open the \psfiles\ folder, and send the file \verb|getfonts.ps|.
The list should appear in the \OzTeX\ window.
If you'd prefer to print the list then send \verb|fontlist.ps|.
The font you wish to use may not reside in the current printer, so
\dvips\ provides a mechanism for downloading non-resident PostScript fonts.
For example, the following line appears in the supplied {\tt psfonts.map} file:
\begin{verbatim}
   putr8r Utopia-Regular "TeXBase1Encoding ReEncodeFont" <8r.enc <putr.pfa
\end{verbatim}
When \dvips\ reads a DVI file, it checks to see if \verb|putr8r| is used
anywhere on a selected page.  If so, the above entry tells \dvips\ to
include {\tt putr.pfa} in the PostScript output (along with {\tt 8r.enc}).
\dvips\ looks for {\tt putr.pfa} in the current folder first and then
in the list of folders specified by \verb|ps_folders|.
Note that \dvips\ can download font information stored in
Macintosh PostScript fonts (i.e., files of type LWFN).
It checks the type of the file specified after ``\verb|<|'' and
if the type is LWFN then it will download the PostScript code stored in
the file's POST resources.
You can keep PostScript fonts anywhere you like, but you do need to
include the path in the \verb|ps_folders| list.
Such fonts are normally kept in the Fonts subfolder of your System folder.
The special \verb|$f| entry at the end of the \verb|ps_folders| list
in the {\tt Default} config file will expand to the correct path.
Partial downloading of PostScript fonts is available via the \verb|-j| option.
Another feature supported by \dvips\ is the downloading of PostScript fonts
used (but not included) in EPSF files.
Such fonts will only be downloaded if they appear in {\tt psfonts.map}
along with a ``\verb|<|'' entry specifying the {\tt pfa}/{\tt pfb}/LWFN
file to be downloaded.  See the bottom of {\tt psfonts.map} in
{\tt :DVIPS:Inputs:} for some examples.
\subsubsection{PostScript fonts on a non-PostScript printer}
To print a DVI file that uses PostScript fonts on a non-PostScript printer,
you must have the corresponding screen fonts installed in your system.
For example, if \verb|ptmr8r| appears in a DVI file then \OzTeX\ will
try to use the screen font Times.
If Times is not installed then \OzTeX\ will display an error
message and use the system font instead (normally Chicago).
When previewing a DVI file, \OzTeX\ will warn you if it can't find the
screen font for a PostScript font; all characters from such a font will
be shown using the system font in the \verb|missing_fonts| color.
\subsubsection{PostScript or Computer Modern?}
There are some important differences between a PostScript font
like Times-Roman and an ``equivalent'' Computer Modern Roman font:
\begin{enumerate}
\item
A PostScript font can be requested at virtually any size.
For example, you can do things like ``\verb|\font\helv=ptmr8r at 33.3pt|''.
You can also ask for {\tt cmr10} at any size,
but a separate PK file is needed for each size.
(However, you can avoid PK files altogether by getting
PostScript versions of the Computer Modern fonts; see below.)
\item
When a PostScript font like Times-Roman is scaled to the same design size
as a CMR font it tends to look darker and larger.  It is not a good idea
to mix the two font designs in the same document.
\item
For Plain \TeX\ users, 
the standard \TeX\ commands for accents and foreign letters need to be
redefined for a PostScript text font.
The file \verb|pstext.tex| in the \verb|Plain| subfolder
in \texinputs\ contains the required macro definitions.
Another file, \verb|psfonts.tex| in \texdocs, inputs these macros and
illustrates the use of PostScript fonts in a Plain \TeX\ document.
\end{enumerate}
\LaTeX\ users can typeset a document with PostScript text fonts rather
than Computer Modern by simply adding a suitable package declaration.
For example,
\begin{verbatim}
   \documentclass{article}
   \usepackage{times}
\end{verbatim}
will switch the default text font to Times-Roman.  See the documentation in
the \verb|PSNFSS| subfolder in \texinputs\ for other possibilities.
Note that CM math fonts will still be needed to typeset mathematics, but you
can buy commercial font packages such as Lucida or MathTime that include
PostScript replacements for these math fonts.
If you like the look of Computer Modern fonts, but you also want the
flexibility of PostScript fonts, then you can have the best of both worlds.
PostScript versions of Computer Modern are available at CTAN sites.
Choose either the BaKoMa fonts created by Basil Malyshev,
or the CM/PS fonts created by Blue Sky Research.
\OzTeX\ provides configuration files for switching to BaKoMa, CM/PS,
Lucida or MathTime.  The corresponding {\tt config.*} files for
\dvips\ are in the {\tt :DVIPS:Inputs:} folder.
\subsection{Macintosh screen fonts}
The font entries listed between \verb|begin_fonts| and \verb|end_fonts|
in a configuration file are not restricted to PostScript fonts.
The entries are really for any non-PK font, and that could be an outline font
in TrueType format, or even some sort of bitmap font in non-PK format.
The critical requirement is that a matching TFM file exists so that
\TeX\ can typeset characters from that font.
When previewing a DVI file containing a non-PK font
(or when printing such a file on a non-PostScript printer),
\OzTeX\ draws characters using the corresponding Macintosh screen font
given in the config file.  If the requested screen font can't be found then 
\OzTeX\ will warn you and use the system font instead.
If you want to use PostScript fonts with \OzTeX\ then for best results
you should install the TrueType or ATM versions of the screen fonts listed
in the {\tt Default} config file.
\subsection{Encoding files}
\label{enc-sec}
Encoding files give you complete control over which Macintosh character
is displayed when a particular PostScript character in a DVI file is
to be viewed or printed on a non-PostScript printer.
(The {\tt .enc} files downloaded by \dvips\ during PostScript printing
serve a similar purpose to \OzTeX's encoding files, but the syntax is
completely different.)
Encoding files are loaded at the time a configuration file is loaded.
Every PostScript screen font must be followed by an encoding entry
which is either the name of an existing encoding file, or \verb|nil| if the
screen font uses the same encoding as its corresponding TFM file.
\OzTeX\ looks for a given encoding file in the current \verb|ps_folders| list
and, if found, uses it to build an encoding array of 256 elements.
This array defines the mapping of DVI character codes into Macintosh characters.
You can see the currently loaded encoding arrays by selecting the appropriate
``Show'' item in the Config menu.
The syntax of an encoding file is described in detail in the standard encoding
file called \stdenc\ which is kept in the \encfiles\ subfolder in \psfiles.
This encoding file maps characters from a standard PostScript text font
into equivalent characters in a standard Macintosh text font.
Depending on the encoding scheme used in your PostScript TFMs or screen fonts,
you might need to create other encoding files.
For an interesting example of how such files can be used,
see the \verb|View CM using PS| configuration file.
\subsection{Virtual fonts}
\label{vf-sec}
Virtual fonts provide a convenient and flexible way to specify a
mapping from \TeX's notion of a font character to the
capabilities of a particular output device (e.g., screen or printer).
In particular, virtual fonts make it easy to use PostScript fonts with \TeX.
The definitive document on virtual fonts is Donald Knuth's article
in TUGboat vol.~11 no.~1.  A text version called ``Knuth on VFs''
can be seen in \OzMF's Help menu.
\OzTeX\ and \dvips\ process virtual fonts automatically,
so most people never need to worry about whether or not a DVI file
uses such fonts.  To decide if font \verb|foo| is virtual,
\OzTeX\ and \dvips\ look for a file called \verb|foo.vf|
in the current folder, then in the list of folders specified by
\verb|vf_folders|.
\newpage
\section{\OzMF}
\label{mf-sec}
\OzMF\ is a companion program for \OzTeX\ which includes various
font related tools.
The most important of these is \mf, a program written by Donald Knuth
and used to create \TeX-compatible fonts.
For more information, see {\sl The METAFONTbook\/} by Knuth.
The other font related tools included in \OzMF\ are:
\begin{description}
\item[\tt MakeTeXPK]
reads a given text file, normally with a {\tt .make} extension,
and uses commands in the file to build one or more PK files.
You don't need to create {\tt .make} files yourself.
If \OzTeX\ is asked to make missing PK fonts then it will pass a
temporary file called {\tt OzTeX-to-OzMF.make} to \OzMF\ so that
{\tt MakeTeXPK} will create the required PK file.
\item[\tt GFtoPK]
converts a GF (generic font) file into a PK (packed pixel) file.
GF files are created by \mf, but most DVI-reading programs
like \OzTeX\ prefer to use PK files, so {\tt MakeTeXPK}
automatically runs {\tt GFtoPK} after running \mf.
\item[\tt GFtoDVI]
converts a GF file into a DVI file.
Used by font designers to create character proofs.
\item[\tt GFtype]
converts a GF file into a human-readable text file.
Mainly used to validate GF files.
\item[\tt PKtype]
converts a PK file into a human-readable text file.
Mainly used to validate PK files.
\item[\tt TFtoPL]
converts a TFM (\TeX\ font metric) file into a PL (property list) file.
\item[\tt PLtoTF]
converts a PL file into a TFM file.
\item[\tt VFtoVP]
converts a VF (virtual font) file into a VPL (virtual property list) file.
\item[\tt VPtoVF]
converts a VPL file into a VF file and a TFM file.
\item[\tt AFM2TFM]
converts an AFM (Adobe font metric) file into a TFM file.
\end{description}
For more details about each tool, see the corresponding items in
\OzMF's Help menu.
\OzMF\ provides some nice features for running these tools in a Mac
environment.  For example, the open-file dialog has a ``Do all files''
button which allows you to process all selected files in the current folder.
Other features worth noting:
\begin{itemize}
\item
All tools can run in the background.
\item
Text files read by \mf, {\tt PLtoTF}, {\tt VPtoVF} and {\tt AFM2TFM}
can have either Return or Linefeed as the end-of-line character,
so Unix text files can be read unmodified.
\item
\mf\ looks for ``\verb|%&base|'' on the first line of a selected
{\tt .mf} file and, if present, uses the given base to override
the currently ticked base in the Metafont menu.
\end{itemize}
The \OzMF\ application should be kept in the same folder as \OzTeX, along
with the \mff\ folder which contains these subfolders:
\begin{description}
\item[\tt Configs]
contains the configuration files used by \OzMF, especially
the {\tt Default} file which is loaded when \OzMF\ starts up.
Like \OzTeX, \OzMF\ can be customized by selecting config files from a
Config menu.
\item[\tt Inputs]
contains a large library of {\tt *.mf} files.
Most of these files contain \mf\ code for creating character bitmaps
(in GF files) and corresponding font metrics (in TFM files).
\item[\tt Bases]
contains {\tt mf.pool} (read by \inimf) and various {\tt *.base} files.
Base files are the \mf\ equivalent of \TeX's format files.
\inimf\ is used to build base files.
Two base files are distributed: {\tt Plain.base} and {\tt MakeTeXPK.base}.
The latter is used by {\tt MakeTeXPK} and contains common \verb|mode_defs|
for Mac printers, plus some settings suitable for Mac screens;
see {\tt MakeTeXPK.mf} in the {\tt Inputs} subfolder.
\item[\tt Help]
contains the files used in \OzMF's Help menu.
\end{description}
\subsection{Making PK fonts on demand}
\label{make-pk}
All of \OzTeX's dialog boxes for printing or viewing a DVI file have a check box
called ``Make missing PK fonts'' (only available in System~7 or later).
If this box is checked and \OzTeX\ detects a missing PK font,
then \OzMF\ will be called to build the required PK file.
\OzTeX\ does not call \mf\ directly.  Instead it starts up
{\tt MakeTeXPK} which runs \mf\ to build a GF (Generic Font) file,
then runs {\tt GFtoPK} to convert the GF file into a PK file.
\OzTeX\ uses the new PK file to continue previewing or printing.
The location of the PK file is determined by the \verb|pk_file| template.
The template in \OzMF's {\tt Default} file will create PK files in the
\pkfiles\ folder.  If you want {\tt MakeTeXPK} to create PK files in
appropriate subfolders of \pkfiles\ then set \verb|pk_file| to
``\verb|:PK-files:%d:%f.%dpk|''.  See the comments at the end of the
{\tt Default} file for details about the \verb|pk_file| template.
If you decide to change the template then make sure it matches one of
the templates in the \verb|pk_files| list used by \OzTeX\ so that
it can find PK files created by {\tt MakeTeXPK}!
It is possible that the font creation process will fail.  For example,
\mf\ might not find the required {\tt .mf} input file.  Or you might decide
to cancel the process.  In such cases \OzTeX\ will report a missing PK font
and append a line of information to a file called \missfont\ in the
\pkfiles\ folder.
If ``Make missing PK fonts'' is \emph{not} checked then \OzTeX\ won't attempt to
create a missing PK font, but it will append a line to \missfont.
This file can be used later by {\tt MakeTeXPK} to build all the
listed PK fonts.  For many people this might be more convenient than
having \OzTeX\ build PK fonts on the fly --- on a slow Mac it can take quite
a while for \mf\ to create a font.
If you don't have a Power Mac,
I recommend leaving ``Make missing PK fonts'' unchecked, at least initially.
Preview all your DVI files and select ``Page Info'' from the View menu.
If there are any missing PK fonts, \OzTeX\ will create a \missfont\ file.
Edit this file and remove any duplicate lines.
Start up \OzMF, select {\tt MakeTeXPK} from the Tools menu,
open \missfont\ and go to bed!  When you wake up,
all the PK files should have been created in the \pkfiles\ folder.
Note that {\tt MakeTeXPK} will keep processing if errors occur.
All error messages are appended to a {\tt MakeTeXPK.log} file in the same
folder as the {\tt .make} file.  This is handy when building lots of PK fonts
because a minor \mf\ error won't stop the entire process.
It is a good idea to delete (or rename) \missfont\ after using it to
build PK files.  \OzTeX\ simply appends missing font info to \missfont\ without
checking to see if that info already exists, and {\tt MakeTeXPK} simply
builds all the listed PK files, even if they already exist.
If you preview a DVI file and select the ``Ignore missing fonts'' check box
then the ``Make missing PK fonts'' setting is ignored.  If a missing PK font
is detected then \OzTeX\ won't attempt to call {\tt MakeTeXPK}, nor will it append
any information to \missfont.  This feature is useful when previewing
certain DVI files (like {\tt trip.dvi}) where you know there are missing fonts
and have no desire to create them.
\subsection{Setting the Metafont mode}
\label{mfmode}
To be able to build a PK file, \mf\ needs to know what mode to use.
\OzTeX\ gets this information from either the \verb|printing_mode| or
\verb|viewing_mode| parameter and simply passes the string on to \mf\null.
For \dvips, the mode string is specified in {\tt config.ps}.
WARNING: The given strings must exactly match known \verb|mode_def| values
defined in either {\tt modes.mf} or {\tt macmodes.mf};
these files are kept in {\tt :Metafont:Inputs:}.
It is also important to make sure the current printing/viewing resolution
matches the \verb|pixels_per_inch| value in the corresponding
\verb|mode_def|, otherwise \mf\ won't create a suitable PK file.
\OzTeX's {\tt Default} config file sets both modes to {\tt laserwriter}.
You might need to change these modes, either by selecting one of the
supplied config files (e.g., StyleWriter),
or by editing the {\tt Default} config file.
If a mode string is empty (\verb|""|) then \mf\ will use the {\tt localfont}
mode which is currently equivalent to the {\tt laserwriter} mode.
Common modes for \OzTeX\ users are
{\tt laserwriter}, {\tt stylewriter}, {\tt imagewriter},
{\tt ljfour} and {\tt linohi}.
If none of these modes suit your particular printer then look in
{\tt modes.mf} to see if there is a suitable definition.  The most important
thing to look for is a \verb|pixels_per_inch| value that matches the resolution
of your printer.  If you can't find a matching \verb|mode_def| (unlikely), you
will have to create your own and run \inimf\ on {\tt MakeTeXPK.mf} to
rebuild {\tt MakeTeXPK.base}.
NOTE:
I've set the {\tt stylewriter} \verb|mode_def| parameters in {\tt macmodes.mf}
to be the the same as the {\tt laserwriter} parameters
(except for \verb|pixels_per_inch| of course).
This was done so that both modes can share the same set of PK files.
People who are fussy about their pixels (or with better eyesight than me)
might want to optimize the {\tt stylewriter} parameters for that printer.
\section{\OzMP}
\label{mp-sec}
\OzMP\ is a Mac implementation of John Hobby's MetaPost program for producing
PostScript pictures using a \mf-like language.  The PostScript files
created by MetaPost don't contain a PICT~256 resource, so you'll need a
PostScript printer to print a DVI file that includes such files.
The \OzMP\ application should be kept in the same folder as \OzTeX, along
with the \mpf\ folder which contains these subfolders:
\begin{description}
\item[\tt Configs]
contains the configuration files used by \OzMP, especially
the {\tt Default} file which is loaded when \OzMP\ starts up.
Before using MetaPost, examine the supplied parameters in the {\tt Default}
file and make sure the search paths for TFM/VF files match those used by
\OzTeX.  Also read the comments at the bottom of the file.
\item[\tt Docs]
contains John Hobby's documentation for MetaPost.  Before printing anything,
select ``MetaPost'' from the Help menu and carry out the given steps.
\item[\tt Help]
contains the files used in \OzMP's Help menu.
\item[\tt Inputs]
contains {\tt *.mp} files.
\item[\tt Mems]
contains {\tt mp.pool} (read by \inimp) and {\tt Plain.mem}.
Mem files are the MetaPost equivalent of \mf's base files.
Use \inimp\ to build mem files.
\end{description}
\OzMP\ includes two supporting tools, {\tt MPtoTeX} and {\tt DVItoMP}\null.
If you are using System~7 or later then you won't need to run these
tools manually because \OzMP\ will call them automatically if
your {\tt .mp} file contains {\tt btex} \ldots{\tt etex} or
{\tt verbatimtex} \ldots{\tt etex} sections.
Such sections contain \TeX/\LaTeX\ code, so \OzMP\ will also call
\OzTeX\ in between {\tt MPtoTeX} and {\tt DVItoMP}.
\section{DVIPS}
\label{dvips-sec}
\OzTeX\ uses Tom Rokicki's \dvips\ program to convert DVI files into
PostScript.  The \dvf\ folder contains all the necessary supporting
files in a couple of subfolders:
\begin{description}
\item[\tt Inputs]
contains various input files required by \dvips, such as
{\tt config.ps}, {\tt psfonts.map} and the {\tt *.pro} files.
\item[\tt Docs]
contains the \dvips\ documentation and some test files.
To print off a copy of the \dvips\ manual, run {\tt dvips.tex} through
\TeX\ and print {\tt dvips.dvi}.
\end{description}
The version of \dvips\ included in \OzTeX\ contains a number
of enhancements:
\begin{itemize}
\item
All the \OzTeX-specific \verb|\special| commands
for including PICT/PNTG/EPSF files are supported.
I've also added support for \OzTeX's method
of including raw PostScript files followed by arbitrary PostScript code,
although this is not something I recommend (EPSF files are much safer).
Because of conflicts with \dvips-specific \verb|\special| commands,
there are some rare situations where inclusion of a raw PostScript file
will no longer work.  In such cases you will need to add a \verb|rawps|
keyword; e.g., \verb|\special{rawps=foo.ps ...}|.
\item
\dvips\ can download Mac PostScript font files (of type LWFN) as well
as the usual {\tt pfa}/{\tt pfb} files.
This is very handy if you want to use the BaKoMa or CM/PS fonts.
\item
A number of {\tt config.*} files have been added to {\tt :DVIPS:Inputs:}
so that you can pass an extra option like ``{\tt -P CMPS}'' to tell
\dvips\ to load {\tt config.CMPS} after {\tt config.ps};
{\tt config.CMPS} contains the line ``{\tt p +psfonts.CMPS}'' which tells
\dvips\ to append the info in {\tt psfonts.CMPS} to {\tt psfonts.map}.
This is useful if you don't want to make changes to the latter file.
\item
The TFM names in {\tt psfonts.*} are case insensitive
for consistency with Mac file names.
\item
The \dvips\ output can be sent directly to the current printer.
\end{itemize}
Users of \dvips\ on other systems should note that the following environment
variables discussed in the \dvips\ manual have been replaced by equivalent
\OzTeX\ parameters:
\begin{tabbing}
\indent \= DVIPSHEADERS\quad \= = \verb|input_folders|\quad \=\kill
\> TEXCONFIG    \> = \verb|ps_folders|    \> (to find {\tt config.ps}, {\tt psfonts.map})\\
\> DVIPSHEADERS \> = \verb|ps_folders|    \> (to find {\tt .pro}/{\tt .enc}/{\tt .pfa}/{\tt .pfb}/LWFN files)\\
\> TEXINPUTS    \> = \verb|input_folders| \> (to find \verb|\special| files)\\
\> TEXFONTS     \> = \verb|tfm_folders|   \> (to find TFM files)\\
\> VFFONTS      \> = \verb|vf_folders|    \> (to find VF files)\\
\> TEXPKS       \> = \verb|pk_files|      \> (to find PK files)
\end{tabbing}
When searching for files, \dvips\ always looks in the current folder
(the same folder as the DVI file) before looking in the folders specified
by the above parameters.
In most operating systems, \dvips\ uses the above environment variables to
override the settings in {\tt config.ps}.
In \OzTeX's case, {\tt config.ps} can be used to override the above parameters,
but it is not something I'd recommend doing unless you are an experienced
\dvips\ hacker.  If you need to do this, note that Mac path names use colons
to separate folders, so you must use commas to separate path names.
NOTE: \dvips\ does \emph{not} use \OzTeX's \verb|printing_resolution| or
\verb|printing_mode| parameters.  It uses the resolution and mode specified
in {\tt config.ps}.  This approach allows more flexibility.
For example, a person with two printers, one QuickDraw and one PostScript,
could set up \OzTeX's printing parameters for the QuickDraw printer and
have quite different settings in {\tt config.ps} for the PostScript printer.
\newpage
\section{Graphics}
\label{graphics}
Creating illustrations with standard \TeX\ commands isn't easy.
Although it is theoretically possible to place small dots
anywhere on a page and build up an arbitrarily complex picture,
time and memory limitations make such a scheme impractical.
(\LaTeX\ provides a \verb|picture| environment, but it is very inefficient
and only suitable for small, simple diagrams.)
\TeX\ does however provide a \verb|\special| command that can be used
to pass arbitrary information to the DVI reader.
For example, \OzTeX\ and \dvips\ can interpret a \verb|\special|
command containing the name of a graphic file and then include that
file in the preview or printed output.
Note that using \verb|\special| can seriously reduce the portability of
your \TeX\ documents because a given DVI-reading program can only understand
\verb|\special| commands that obey its own particular syntax.
One useful technique to enhance portability is to
hide the actual \verb|\special| call inside a macro; then when you move your
\TeX\ file to another computer all you need to do is change the macro
definition (assuming the DVI translator supports similar functionality
in its handling of \verb|\special|).
\LaTeX\ users should never need to use explicit \verb|\special| commands.
The \verb|graphics| and \verb|graphicx| packages make it easy to include
graphic files.  Plain \TeX\ users can also use macro packages;
see Larry Siebenmann's \verb|boxedeps.doc| and \verb|boxedeps.tex| in
the \verb|Plain| subfolder in \texinputs.
Another alternative is \verb|epsf.tex|; see \verb|epsftest.tex| in the
\texdocs\ folder.  Using a macro package will make your input files
much more portable.
%Most people can probably ignore the following subsections.
%They are provided for people who need to know all the gory details
%about the \verb|\special| syntax supported by \OzTeX.
\subsection{Including Macintosh graphic files}
A \verb|\special| command can appear almost anywhere in an input file.
It behaves like an invisible box of zero height and width.
\TeX\ simply stores the given information in the DVI file at the current
page position.
When previewing a DVI file, \OzTeX\ draws a small marker indicating the
location of a \verb|\special|.
The ``Page Info'' item will display this location in paper coordinates
as well as the text of the \verb|\special| command.
\OzTeX\ allows the inclusion of three common types of Macintosh
graphic files:
\begin{itemize}
\item
PICT files can be generated by almost all drawing/painting programs
on the Macintosh.  A quick way to get a PICT file if you're using System~7
is to type Shift-Command-3.
To include a PICT file, use a command of the form:
\verb|\special{pict=filename}|
Note that \OzTeX\ converts the PICT file into a black and white bitmap
for previewing and printing, so you won't see any colors.
The bitmap is always at 72\,dpi when previewing, but the current
printing resolution is used when printing.
\item
PNTG files are also very common --- they're better known as MacPaint files.
(Shift-Command-3 on a Mac running System~6 or earlier will create a screen
dump in a file of type PNTG\null.  If you have a color monitor you'll
first need to set it to black and white.)
To include a PNTG file, use a command of the form:
\verb|\special{pntg=filename}|
\item
EPSF files are becoming increasingly common.
They contain encapsulated PostScript code in the data fork which \OzTeX\ uses
when PostScript printing, and a corresponding PICT resource (ID = 256)
which \OzTeX\ uses when previewing or non-PostScript printing.
To include an EPSF file, use a command of the form:
\verb|\special{epsf=filename}|
\end{itemize}
Keywords and file names are case insensitive
and spaces before the file name are ignored.
For example, \verb|\special{EPSF=FOO}| is the same as \verb|\special{epsf= foo}|.
To find a given \verb|\special| file, \OzTeX\ uses the same search strategy as
that for a \TeX\ input file.  It looks in the current folder first, and then in
the \verb|input_folders| list.
The file name can also be a path name relative to the current folder, or a full
path name.  For example,
\begin{verbatim}
   \special{pict=:my-pict-files:foo}
\end{verbatim}
will include a file called \verb|foo| from a subfolder called \verb|my-pict-files|
in the current folder.
Spaces and other special characters (like \verb|=|) can be included in a file
name or path name by enclosing them in double quotes.  For example,
\begin{verbatim}
   \special{pict="my pict file"}
\end{verbatim}
will include a file called \verb|my pict file|.
Using spaces and other unusual characters in a file name is not recommended,
particularly if \TeX's \verb|\input| command might be used to read the file
(as in the \verb|boxedeps.tex| and \verb|epsf.tex| macros).
Also avoid using double quotes in a file name.
The PICT/PNTG/EPSF \verb|\special| commands all allow you to preview graphics
in your DVI file, but if you have a choice, use EPSF files because:
\begin{enumerate}
\item
The output on a PostScript printer should be of much higher quality than a
similar PICT/PNTG image.
\item
A colored EPSF picture will print correctly on a PostScript printer
(assuming it supports color) even though \OzTeX\ will convert its PICT
resource into a black and white bitmap when previewing.
\item
Macro packages like \verb|boxedeps.tex| and \verb|epsf.tex| can extract the
bounding box information in an EPSF file and position the image automatically.
\item
Encapsulated PostScript is supported on many other computers.
\end{enumerate}
Some EPSF files, especially those created on other computers or by programs
like MetaPost, do not contain a PICT~256 resource.
When previewing a DVI file that includes such files,
\OzTeX\ will draw a rectangle showing the bounding box,
along with the name of the file and the message ``no PICT''
near the \verb|\special| marker.
If you try to print the DVI file on a non-PostScript printer then
\OzTeX\ will generate error messages.
When creating a PICT/PNTG file it doesn't really matter where you position
the picture; \OzTeX\ will convert it to a black and white bitmap,
find the smallest bounding box of all black pixels in the bitmap,
then place the bounding box so that its bottom left corner coincides
with the location of the \verb|\special|.
\OzTeX\ does much the same thing for an EPSF picture; it places the lower left
corner of the bounding box at the location of the \verb|\special|.
The only difference is that if the PICT~256 resource is available
(for preview or non-PostScript printing) then \OzTeX\ makes no attempt to
determine the smallest bounding box of all black pixels in the picture.
This is because the picture's dimensions should match those of the
BoundingBox comment in the data fork
(\OzTeX\ will warn you if the dimensions differ by more than 3\,bp).
\OzTeX\ allows optional \verb|keyword=value| pairs after the file name
in a PICT/PNTG/EPSF \verb|\special|.
The keyword can also be terminated by a space.
Here are the currently supported keywords:
\begin{itemize}
\item
\verb|scale=|$n$ --
scales a picture by a factor $n$ ($n$ must be $> 0.0$ and $\le 100.0$).
\item
\verb|hscale=|$n$ --
sets the horizontal scale factor (and alters the aspect ratio).
\item
\verb|vscale=|$n$ --
sets the vertical scale factor (and alters the aspect ratio).
\item
\verb|width=|$bp$ --
sets the horizontal scale to get a picture at the desired width
($bp$ is a number $> 0.0$ and $\le 32000.0$ in bp units, where 72\,bp = 1\,in).
If no previous \verb|height| keyword has been used then the vertical scale is
set to the new horizontal scale to preserve the aspect ratio.
\item
\verb|height=|$bp$ --
sets the vertical scale to get a picture at the desired height.
If no previous \verb|width| keyword has been used then the horizontal scale is
set to the new vertical scale to preserve the aspect ratio.
\end{itemize}
If a particular keyword is used more than once in a single \verb|\special|
command then the last value is used.
An illegal keyword or value will produce an error message when previewing
or printing.  Synonyms exist for most keywords:
\begin{tabbing}
\indent \= \verb|vscale|\quad \=\kill
\> \verb|epsf|   \> =\quad \verb|eps| or \verb|epsfile|\\
\> \verb|pict|   \> =\quad \verb|pictfile|\\
\> \verb|pntg|   \> =\quad \verb|macpaint|\\
\> \verb|hscale| \> =\quad \verb|xscale|\\
\> \verb|vscale| \> =\quad \verb|yscale|\\
\> \verb|width|  \> =\quad \verb|wd|\\
\> \verb|height| \> =\quad \verb|ht|
\end{tabbing}
Here are some examples of how to use \verb|\special| commands:
\begin{enumerate}
\item
To include a picture at ``normal'' size:
\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon}}%
\verb|\special{pntg=ozicon}|
\item
To halve the size:
\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon scale=0.5}}%
\verb|\special{pntg=ozicon scale=0.5}|
\item
To double the width:
\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon hscale=2}}%
\verb|\special{pntg=ozicon hscale=2}|.
\item
To set the height to 0.2\,in and the width to 2\,in:
\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon ht=14.4 wd=144}}%
\verb|\special{pntg=ozicon ht=14.4 wd=144}|.
\item
To set the height to 0.5\,in and preserve the aspect ratio:
\leavevmode\rlap{\hskip 4in
      \special{pntg=ozicon ht=36}}%
\verb|\special{pntg=ozicon ht=36}|.
\end{enumerate}
The figure on page~\pageref{folders} of this user guide was created by using
\begin{verbatim}
   \special{pntg=folders scale=0.72}
\end{verbatim}
to include an extract from a Macintosh screen dump.
The scale value of $0.72$ was chosen because it is a multiple of
$0.24 = 72/300$, where 72\,dpi is the resolution of the MacPaint bitmap
and 300\,dpi is the resolution of my printer.
This technique can improve the print quality of scaled bitmaps.
\subsection{Compatibility with other DVI translators}
To provide better \verb|\special| compatibility with \dvips\ and other
DVI translators, \OzTeX\ can process \verb|\special| commands like
\begin{verbatim}
   \special{psfile=foo llx=100 lly=100 urx=172 ury=172 rwi=720 rhi=720}
\end{verbatim}
where \verb|rhi| is optional (it is used to change the aspect ratio).
Note that \verb|llx| and the other keywords shown above can only be used
after \verb|psfile|.  Their order doesn't matter.
It is best \emph{not} to type in such \verb|\special| commands yourself;
you should let a macro package generate them.
The given file (\verb|foo| in the above example) should normally be an
EPSF file containing a BoundingBox comment.
For compatibility with Wilfried Ricken's Direct\TeX,
\OzTeX\ also allows PICT files in a PSFILE \verb|\special|.
If \verb|foo| is a file of type PICT then \OzTeX\ will read in the picture
stored in the data fork.
If the given file name ends in ``\verb|.pict|'' then \OzTeX\ will get the
picture from a PICT~256 resource (and if you put a suitable BoundingBox
comment in the data fork then \verb|epsf.tex| or \verb|boxedeps.tex|
can be used to position the image).
Note that if the given file does not contain a BoundingBox comment
(PICT files cannot have such a comment)
then you will need to supply the bounding box coordinates to \verb|epsf.tex|;
for example, \verb|\epsfbox[0 0 72 72]{foo}|.
The numbers must be given in bp units and in the following order:
lower left x, lower left y, upper right x, upper right y.
\subsection{Including PostScript files}
\OzTeX\ allows you to include a ``raw'' PostScript file
using \TeX's \verb|\special| command.  However, if you have a choice then
any of the methods described in the above sections          % XREF
are preferable because \OzTeX\ cannot preview such a file,
nor can it print the file on a non-PostScript printer.
Assuming you have a file called \verb|fig.ps| that contains
PostScript code for generating some sort of figure, the following command
can be used to include this figure in a \TeX\ or \LaTeX\ document:
\begin{verbatim}
   \special{fig.ps}
\end{verbatim}
When printing the DVI file, \OzTeX\ interprets the \verb|\special| argument as
a file name and then includes this file with the rest of the PostScript output.
If it can't find the file in the current folder then it looks in the
\verb|ps_folders| list.
Don't worry about removing any \verb|showpage| command at the end of
your PostScript file because \OzTeX\ temporarily disables it.
It may take a little practice to position the figure correctly.
The default PostScript origin is at the bottom left corner of the paper.
However, when you include a file, \OzTeX\ automatically moves the
origin to the position of the \verb|\special|.
You can move the figure about by shifting the \verb|\special| position,
or by using a \verb|translate| command in the PostScript file.
The latter option is faster because you don't have to run \TeX\ again.
Alternatively, you may prefer to place your figure at an absolute position on
the paper.  Simply use a command like \verb|initgraphics| in the PostScript
file.  The position of the \verb|\special| command then becomes irrelevant;
just make sure it's on the right page!
\OzTeX\ also allows arbitrary PostScript code to appear after the file name.
At least one space must be used to terminate the file name;
further characters are included as a new line at the {\em start\/} of
the given file.
For example,
\begin{verbatim}
   \special{fig.ps 2 1 scale}
\end{verbatim}
could be used to double the width of the figure.
This feature allows you to include the same PostScript file more than once,
but with a different starting line each time --- useful if you need to produce
the same diagram many times but with slight variations.
\subsection{Rotating \TeX\ material}
\label{rotation}
If you have a PostScript printer then rotating arbitrary \TeX\ material
is quite simple.  \LaTeX\ users can use the \verb|\rotatebox| command
from the \verb|graphics|/\verb|graphicx| packages; see the examples in
\verb|:TeX-inputs:Graphics:grfguide.tex|.
Plain \TeX\ users should check out the examples in
\verb|:DVIPS:Docs:rotsample.tex|.
\subsection{Color}
\label{color}
\OzTeX's previewer supports the color \verb|\special| commands used by
\dvips\ and generated by \LaTeX's {\tt color} package.
The {\tt hyper.tex} file in \latexdocs\ shows how the {\tt color} package
can be used.  For more details, \LaTeX\ users should read
{\tt :TeX-inputs:Graphics:grfguide.tex}
and Plain \TeX\ users should read the final section in the \dvips\ manual. % XREF
If your DVI file uses color \verb|\specials| then you should enable
the ``Prescan color \verb|\specials|'' option in the view dialog.
Prescanning might be needed because \OzTeX\ allows you to jump to any page,
but there might be a \verb|\special| on an earlier page that sets the text color
(or the background) for all future pages.  The prescan option tells \OzTeX\ 
to do a quick scan of \verb|\specials| on all earlier (unseen) pages to make sure
that the colors on the current page are correct.  Although this scan is
quite fast --- a mid-range Mac takes about 2 seconds to scan 50 pages ---
it is still slow enough that you should keep the prescan option disabled
if you never use color.  \OzTeX\ remembers the state of the prescan option.
When \OzTeX\ sees a page for the first time, the color \verb|\specials| on that
page are remembered.  As more pages are seen, the prescan will take less time.
In fact, if you preview pages 1, 2, 3, etc., the prescan isn't done at all.
NOTE: The color \verb|\specials| are not yet supported for QuickDraw printers;
that will have to wait until I buy a color printer.
\subsection{Hyper\TeX}
\label{hype}
\OzTeX's previewer supports the Hyper\TeX\ \verb|\special| commands.
These \verb|\specials| let you jump to another place in a document by
simply clicking on a link, such as a reference to a section number.
The {\tt hyperref} package (in {\tt :TeX-inputs:HyperRef:}) makes it
very easy for \LaTeX\ users to add Hyper\TeX\ links to their documents.
Just add the line \verb|\usepackage{hyperref}| before \verb|\begin{document}|,
delete any {\tt .aux} and {\tt .toc} files (to avoid a {\tt hyperref} bug),
then run \LaTeX\ a couple of times.
To see how Hyper\TeX\ links work, preview the DVI files in
the \latexdocs\ folder.  All links are underlined and, on a color monitor,
are colored green.  If the mouse moves over a link then the cursor changes
to a pointing finger.  Clicking on a link will take you to the target.
The ``Back Link'' and ``Forward Link'' items in the View menu
make it easy to move to previously visited links; they work just like the
Back/Forward buttons in a Web browser.
Their keyboard short cuts are ``\verb|[|'' and ``\verb|]|'' respectively.
NOTE: At the moment, \OzTeX\ only supports internal links (links to targets
within the same DVI file).  Eventually I hope to support links to other DVI
files on your Mac or anywhere on the Internet.
The Hyper\TeX\ \verb|\special| commands are also supported by \dvips.
If the \verb|-z| option is given then \dvips\ will generate ``HyperPostScript'';
this can be run through Adobe Distiller to produce a PDF file with hypertext links.
For more information, see the article by Mark Doyle in TUGboat vol.~16 no.~2,
or visit \verb|http://xxx.lanl.gov/hypertex/|.
\newpage
\section{Recovering from errors}
\OzTeX\ reports errors by displaying a message in the \OzTeX\ window
or in a dialog box.  In the latter case there are two types of error dialogs:
\begin{enumerate}
\item
Warning messages appear in a box with two buttons: Cancel and Continue.
The former lets you cancel a whole heap of \verb|\special| errors when
viewing a DVI file (try page 16 in \verb|nasty.dvi| for example).
\item
Fatal messages appear in a box with a Quit button (which will quit \OzTeX).
\end{enumerate}
Most errors, particularly the serious ones, are accompanied by a beep.
Let's now look at the most likely errors you'll encounter and discuss
what you can do to prevent them recurring.
\subsection{Errors when loading a configuration file}
\label{config-error}
If an error occurs while loading in a configuration file then \OzTeX\ will
display a suitable message in the \OzTeX\ window.
The error message will also include the line number in the file.
It is advisable to switch to your editor, fix the error and reload the
configuration file before attempting to do anything else, particularly if
the error is in the {\tt Default} file.
See section~\ref{config-syntax} for a precise
description of the syntax required in a configuration file.
\subsection{Errors when loading an encoding file}
These errors can occur when \OzTeX\ is loading a configuration file
containing a list of PostScript fonts.
If \OzTeX\ complains that it can't find an encoding file, check the
\verb|ps_folders| parameter in the configuration file.
The encoding files supplied with \OzTeX\ are all stored in
the \encfiles\ subfolder in \psfiles.
\OzTeX\ does \emph{not} look in the current folder for an encoding file.
Various syntax errors are possible when reading an encoding file.
The resulting message should provide you with enough information to fix
the problem.
See the comments at the start of \stdenc\ for a detailed description of
the legal syntax.
\subsection{Errors when running \TeX}
Nearly all the errors you'll see when running \TeX\ will be the
result of mistakes in your input file.
\texbook\ is the best place to look for solutions, especially Chapters~6 and 27.
Lamport's \LaTeX\ manual also has a section devoted to errors.
The following errors are more likely to occur due to \OzTeX's particular
implementation of \TeX.
\subsubsection*{Can't find file}
There are a number of likely reasons why \TeX\ can't find a file:
\begin{enumerate}
\item
The file does not exist in either the current folder or in any of the
subfolders within \texinputs.
If \TeX\ was looking for a format file then make sure it is in the
\texformats\ folder.
\item
You could have spelt the file name incorrectly.
\item
The file name might contain an illegal character.
A Macintosh file name can contain just about any character, but
\TeX\ is not so flexible.
Don't use spaces and avoid non-alphabetic characters in all file names
that might be seen by \TeX\null.
\end{enumerate}
If you see such an error then the best thing to do is hit Command-dot
to abort \TeX\ and either rename the file or move it to the correct folder.
\subsubsection*{Not enough memory}
The most likely time you could run out of memory is when using \initex\ to
create a format file.
\initex\ typically requires more memory than \TeX\ --- just
how much more depends on the \TeX\ parameters in your configuration file.
If you do run out of memory then quit \OzTeX,
select the \OzTeX\ application icon, choose ``Get Info'' from the Finder's
File menu, and increase the preferred size.
\subsubsection*{Fatal format error}
You probably changed one of the critical \TeX\ parameters in your configuration
file and forgot to rebuild the format.
Run \initex\ and rebuild the offending format file (see section~\ref{fmt-sec}).
\subsubsection*{\TeX\ capacity exceeded}
\label{capacity}
Such an error message will be accompanied by additional text
describing which parameter has been exceeded.
Before doing anything else, first check for some common errors.
If the exceeded parameter is \verb|stack_size| then make sure
you haven't defined an infinitely recursive macro.
Look at the list of \TeX\ parameters in your configuration file and check
if the exceeded parameter appears there; if it is listed then you might be
able to solve the problem by simply increasing the parameter's value and
reloading the configuration file.
Note that if you change the value of \verb|mem_top|, \verb|hash_size|,
\verb|hash_prime| or \verb|hyph_size| then you will also need to rebuild all
format files (see section~\ref{fmt-sec}).
\subsection{Errors when viewing a DVI file}
\subsubsection*{Missing fonts}
During interpretation of a DVI page you may get a warning message if \OzTeX\ can't
find a PK file, or if a PostScript font's matching screen font is not installed.
Such warnings will only appear once for each missing font
(but not at all if the ``Ignore missing fonts'' check box was selected).
The ``Page Info'' item indicates all missing fonts.
\mf\ can be used to build missing PK files; see section~\ref{mf-sec}.
\subsubsection*{Page off paper}
If \OzTeX\ detects that any part of a DVI page
is off the paper then it will beep and show a full view.
\TeX\ will often catch these errors
(e.g., overfull \verb|\hbox| or \verb|\vbox|)
but there are quite a few situations where it can't.
\TeX\ really has no idea about what paper size you intend to print its pages on.
If you're sure the problem isn't in your input file then
use the ``Page Info'' item to see what \OzTeX\ thinks the paper dimensions are.
You could have forgotten to reset the landscape option or you might have made
a mistake when changing the paper dimensions in a configuration file.
\subsubsection*{{\tt\char'134special} errors}
When interpreting a DVI page \OzTeX\ will check any \verb|\special| commands
and warn you about the following problems:
\begin{itemize}
\itemsep=0pt
\item
An unknown keyword.
\item
A file that can't be opened.
\item
A file type that does not match the first keyword (PICT/PNTG/EPSF).
\item
A bad value after an optional keyword.
\end{itemize}
No warnings appear if the ``Ignore bad \verb|\specials|'' option is checked.
\subsection{Errors when printing a DVI file}
\OzTeX\ detects basically the same set of errors whether it is viewing or
printing a DVI file.  In the latter case the error messages appear in
the \OzTeX\ window along with a beep.
If you've been sensible and previewed the DVI file before printing it then
you should have discovered nearly all the errors (and fixed them).
To avoid wasting paper you should always view a DVI file before printing it
and choose ``Page Info'' to check for any missing fonts
(but don't worry about missing screen fonts if you have a PostScript printer).
Another way to check for errors is to send PostScript output to a file
instead of the printer, although this won't detect certain errors that
can only occur with a non-PostScript printer.
\subsubsection*{Non-PostScript scaling errors}
\label{scaling-probs}
Before \OzTeX\ starts non-PostScript printing, it checks to see that the
\verb|printing_resolution| parameter matches the actual resolution of your printer.
If the resolutions don't match then \OzTeX\ will warn you that scaling problems
may occur.  This warning appears just before the print dialog in case you want
to Cancel printing (you might have forgotten to switch to the correct
configuration file).
If you decide to go ahead and print the DVI file, you might see problems
such as horizontal gaps at regular intervals down each page.
\OzTeX\ prints a page by sending a sequence of horizontal bands to the printer.
The number of bands depends on how much memory is available (the band height
is displayed when showing statistics).  Scaling problems can result in gaps or
overlapping at band boundaries, but they can be avoided by bumping up \OzTeX's
memory to a suitably large value so that only one large band is needed to print
each page.
\subsubsection*{Printer errors}
While sending output to any type of printer you might get status messages
indicating a problem such as an empty paper tray or a paper jam.
Once you've fixed the problem printing can normally continue.
\subsubsection*{Can't open {\tt\char'134special} file}
\OzTeX\ expects the argument of a \verb|\special| command to contain
a file name.  It won't be able to open the file if you spelt its name
incorrectly or if the file isn't in the correct folder.
\subsubsection*{Bad {\tt\char'134special} command}
If \OzTeX\ detects any sort of error in a \verb|\special| command
then a suitable message will be displayed in the \OzTeX\ window.
Note that you will get an error message if you try to print a DVI file that
includes a ``raw'' PostScript file on a non-PostScript printer.
See section~\ref{graphics} for the \verb|\special| syntax and semantics
supported by \OzTeX.
\subsubsection*{PostScript errors}
You shouldn't see any errors in the PostScript code generated by \dvips,
but there may well be problems in a PostScript file included by \verb|\special|.
(You can always tell which is the culprit by commenting out the \verb|\special|
command.)
If you are sending the output to a printer rather than spooling software then
any PostScript error should cause a message to appear in the \OzTeX\ window.
Any further output will be flushed and printing cancelled.
So what can you do?  For starters, get the
{\sl PostScript Language Reference Manual\/} by Adobe Systems.
Debugging a PostScript program can be a frustrating experience.
Try downloading the error handler stored in \verb|errhandler.ps|.
If the problem isn't obvious then use \verb|print| and \verb|flush| commands
to isolate just where the error is occurring.
The Ghostscript program mentioned in the ``Related Software'' help file
can also be useful.
\section{Changing resource data}
This section is for people who know how to use a resource editor like ResEdit.
Most user preferences for \OzTeX\ are stored as resources in a file called \ozprefs.
You might like to change the following resources in this file:
\begin{itemize}
\item
STR~200 and 201   % XREF
specify the location and name of the default configuration file.
\item
STR~240 and 241   % XREF
specify the dimensions of the magnified rectangle that appears
after clicking in the view window.  If you want the magnified area to fill
the view window then set both numbers to huge values (8000 should do).
Setting either number to a value less than 5 will prevent any magnification.
\item
STR~300 to 316   % XREF
specify the keyboard short cuts used when previewing
(see section~\ref{shortcuts}).  All the resources are named,
so it is easy to see which string corresponds to which short cut.
\OzTeX\ uses the first character in each string.
You might need to open a string resource with the hex editor if you want
to insert a non-displayable character like Delete or Return.
\end{itemize}
Some read-only information is stored as resources in the \OzTeX\ application.
For example, STR~12345 specifies the name of the preferences file.
The MENU resources can also be modified.  You might want to change the
name of a menu item or add a new Command-key equivalent.
Note that \OzMF\ and \OzMP\ have their own preferences files.
\section{Transferring TFM/VF/PK/DVI files}
\OzTeX\ reads standard TFM/VF/PK files,
and reads and writes standard DVI files.
If you have access to \TeX\ on some other computer system, you should be able
to move such files to and fro without any further processing.
For the purposes of data transmission a TFM/VF/PK/DVI file must be treated as
a binary file (a stream of arbitrary 8-bit bytes).
When using Kermit to transfer binary files from another computer to your Mac,
remember to type ``\verb|set file type binary|'' before using
the \verb|send| command.
The same goes for receiving such files from your Mac, but with one exception:
to transfer a DVI file created by \OzTeX\ to a VAX/VMS host you'll need to
type ``\verb|set file type fixed|'' before using the \verb|receive| command.
If you have access to the Internet then there is a huge library of
TFM/VF/PK files available by anonymous ftp from many archive sites.
When using ftp to transfer such files, remember to type the
``\verb|binary|'' command before using ``\verb|get|''.
If you transfer a DVI file to your Mac and a mistake occurs during transmission,
or if you forgot to send it as a binary file, then \OzTeX\ will display
some sort of error message soon after opening the file.
Note that a DVI file contains TFM file names;
this can be a cause for concern if you plan to transfer DVI files from one
\TeX\ system to another system with a different set of TFM files.
Another cause of portability problems are \verb|\special| commands.
If you have a choice, it's always safer to transfer the original \TeX\ input
file so you can edit any incompatible font names or \verb|\special| commands.
\section{Getting more information}
Many \TeX-related books are available through TUG, the \TeX\ Users Group.
They also produce an excellent magazine called TUGboat.
Anybody planning to use \TeX\ a lot is strongly advised to join.
The ``\TeX\ Users Group'' item in the Help menu explains how to get in touch.
If you have access to the Internet then another good source of help and
information about \TeX-related topics is the {\tt comp.text.tex} newsgroup.
\bigskip
\bigskip
\bigskip
\begin{center}
*\qquad *\qquad *
\end{center}
\end{document}